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&) Method and system for dynamic volume tracking in an installable file system. 


@) The invention comprises a method for mounting a file system for use in communicating with a data storage 
device and a computer system comprising the steps of: 
a) including a plurality of file system modules in a computer operating system including a default file system 
wherein said file systems are organized in a linked sequence; 
b) coupling a data storage device to said computer system: 
c) detecting a change in media in said data storage device or the first time said computer system accesses 
said data storage device; 
d) loading a file system identified in said list of file systems; 
e) reading a volume ideniifier from said media wherein the location of said volume identifier is specified by 
said loaded file system; 
f) comparing the read volume identifier from said media with the identifier associated with said file system: 
g) mounting said file system if said identifiers match; 
h) loading the next file system identified in said list of file systems if said identifiers do not match; 
i) returning to step (e) until each file system in said list of file systems has been tested or until! a match is 
found; and 
j) mounting a default file system if no match is found. 
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METHOD AND SYSTEM FOR DYNAMIC VOLUME TRACKING IN AN INSTALLABLE FILE SYSTEM 


Included in the specification is Appendix |, which is four sheets of microfiche containing 385 frames. 


Field of the Invention 
This invention relates to the field of computer control systems and more specifically to a method and 
means for facilitating communication between the devices which comprise a computer system. 


Background of the Invention 


Computer systems typically comprise a central processing unit, random access memory, read only 
memory, and a variety of peripheral devices such as data input devices, data output devices, and a variety 
of non-voiatile data storage devices such as floppy disks and fixed or hard disks. Communication between 
the respective devices in a computer system is typically controlled by a computer operating system. One 
well known computer operating system is the MS-DOS operating system available from Microsoft. 

In the MS-DOS operating system, a single file system describes and defines the organization of files 
stored on peripheral devices. In order for the computer system to read or write data in a format recognized 
by both the computer system and the respective peripheral devices, data must be organized in accordance 
with this file system. For example, in a conventional floppy disk peripheral device used with the MS-DOS 
operating system, data on a floppy disk is structured in accordance with a file system known as the FAT file 
system which is so named because of its use of file allocation tables. Tne FAT file system is one of the 
most widely used file systems in the world today. Other file systems may be associated with other types of 
data storage types of peripheral devices such as tape storage devices. 

File systems facilitate communication between the operating system kernel and device dependant 
drivers and are responsible for converting read and write commands generated by an operating system 
kernel (as well as functions such as opening and closing files) into a.form which may be recognized by the 
device driver. 

When using the MS-DOS operating system, the operating system must be configured to define the 
relevant file systems to be used with specific peripheral devices employed by the computer system. Once 
the file systems are defined, file systems remain static or unchanged unless the operating system is 
modified. This typically requires extensive programming effort and is typically quite time-consuming. It 
further requires extensive knowledge of the computer operating system and individuals who do not have 
access to operating system details can not easily modify the file systems. 

Furthermore, in prior systems, disk media which contains files of foreign file systems may not by used 
with the native system. For example, over the years, many computer systems have been developed by a 
variety of manufacturers, each of which are based on alternate file system structures. With current static file 
system architectures, disk media from one system typically will not function with another type of system. As 
computers become more popular, it is increasingly important that files may be shared among all types of 
computer systems. No system is known which allows disk media from virtually all known computer systems 
to be automatically recognized and read in a single operating environment. Further. no system is known 
which allows file systems to be added to a system or modified without the need for altering the computer 
operating system kernel. 


Summary of the Invention 


Briefly described, the present invention contemplates a method and means for automatically identifying 
media used with the computer system and for automatically and dynamically mounting a file system which 
recognizes the media. in accordance with a preferred embodiment of the present invention, one or more 
data storage devices and a plurality of file system drivers are provided in a computer system including a 
default file system wherein the file systems are organized in a linked sequence. The computer system 
continuously monitors all peripheral devices in the system to detect any change in media in the peripheral 
storage devices. Whenever media in a data storage device is changed, or the first time the computer 
system accesses a data storage device, the first file system driver identified in the list of file system drivers 
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is loaded and a volume identifier is read from the media wherein the location of the volume identifier is 
specified by the loaded file system driver. The volume identifier read from the media is then compared with 
the identifier associated with the file system driver and the file system driver is mounted if the identifiers 
match. Otherwise, the next file system driver identified in the linked list of file system drivers is loaded. 

The process is then repeated until each file system driver in the linked list of file system drivers has 
been tested or until a match is found. A defauit file system is mounted if no match is found. 

Accordingly, it is an object of the present invention to provide a method and means for allowing a 
computer system to identify any of number of types of media and to mount the proper file system to be 
used with that media. 

lt is another object of the present invention: for automatically mapping file systems to uncertain media. 

lt is yet another object of the present invention to provide a computer system which can automatically 
adapt to uncertain media without interaction from a user. 

lt is still another object of the present invention to provide an improvement to computer operating 
systems wherein file systems may be modified or added to the system without requiring modification of the 
operating system kernel. 

ft is another object of the present invention to provide a method and means for automatically mapping 
of file systems to uncertain media wherein all dependencies on the format of the media are encapsulated in 
the appropriate file system. 

It is still another object of the present invention to provide a method and means for allowing a computer 
system to be booted from an arbitrary installable file system. 


Brief Description of the Drawings 
These and other objects may be fully appreciated through the detailed description of the invention 

below and the accompanying drawings in which: 
Figure 1A is a block diagram of a computer system constructed in accordance with the principles of the 
present invention. 
Figure 1B is a diagram showing the operating and file system architecture the system of Figure 1A. 
Figures 2A is a diagram detailing the file system structure of the MS-DOS operating system. 
Figure 2B is a diagram detailing the file system structure of the installable file system of the present 
invention. 
Figure 3 is a more detailed diagram of the system of Figure 2B. 
Figure 4 is a diagram showing the disk format of the FAT file system. 
Figures 5A-5H are diagrams showing the disk format of an installable file system adapted for use with 
the present invention. 
Figure 6 is a flow diagram detailing the overall operation of the mount process of the present invention. 
Figure 7 is a diagram of the structure of the installable file system of the present invention. 
Figure 8 is a flow diagram detailing the execution of name-based operations in accordance with the 
principles of the present invention. 
Figure 9 is a flow diagram of the parsing process invoked by the named-based operations process. 
Figure 10 is a flow diagram of the execution of handle-based operations in accordance with the 
principles of the present invention. 
Figure 11 is a flow diagram of the FSH_DoVollo process invoked by the processes described in 
conjunction with Figures 8 and 10. 


Detailed Description of the invention 

Figure 1 shows a computer system 100 which is constructed in accordance with the principles of the 
present invention. The system 100 comprises a central processing unit or microprocessor 102, random 
access memory 104, read only memory 106, input devices such as a mouse 108 and keyboard 110, output 
devices such as display 112 and printer 114 and a variety of non-volatile storage devices such as floppy 
disk drive 116, hard disk drive 120, CD-ROM drive 122, and tape drive 124. In addition, the computer 
system 100 is adapted for communicating with a network 126. Non-volatile storage means that data is 
present when the device is powered-off. © 

in prior systems, an operating system is statically configured with file system drivers wherein each 
peripheral device is compatible with only one media type and file system driver. If media is placed in a 
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drive which is not compatible with the designated file system driver, the media cannot be successfully 
accessed. The present invention provides a method and means for automatically mapping media to the file 
systems associated therewith independent of the peripheral device and without imposing any requirements 
on the format or location of data on the media, as will be-further discussed below. For example, it is 
contemplated that the floppy drive unit 116 may be used with volumes formatted in accordance with a 
number of file systems wherein volume 128 is formatted in accordance with the FAT file system, volume 
132 is formatted in accordance with the well known High Sierra file system and volume 130 is formatted in 
accordance with yet another file system. Similarly, various partitions of hard disk 120 may also be formatted 
in accordance with a number of files systems as indicated by volumes 134, 136 and 138. Similarly, the CD- 
ROM and tape system 124 may be used with volumes 140, 142, respectively, formatted with their own file 
systems. Further, network 126 may be coupled to any number of networks having servers which may 
operate in accordance with their own file systems. 

The operation of the system 100 is coordinated by an operating system which may be any of a number 
of well known operating systems. However, the present invention is particularly adapted for use with the 
OS/2 operating system developed by Microsoft. The structure of the operating environment of the present 
invention is shown in Figure 1B. Typically, an application 152 generates file system requests which are 
processed by kernel 154. The kernel then routes this request to an appropriate file system driver (FSD) 156 
-170. Any file system driver may cooperate with a number of hardware devices. For example, the High 
Sierra file system 156 may be used with CD-ROM player 122 and disk drive 116 when preforming file 
system operations on volumes 172, 174, respectively. Similariy, the FAT file system and the HPFS file 
systems may both be used for performing file system operations on volumes 176, 178, each of which are 
resident on hard disk 120. Further, the FAT file system driver may be used with disk drive 116 when 
performing file system operations on volume 180. Accordingly, the present invention provides a method and 
means for automatically and dynamically mapping uncertain media to the appropriate file system, regard- 
less of the type and format of the file system. 

Figure 2A shows the file system structure of the prior art MS-DOS operating system. In the MS-DOS 
operating system 200, the FAT file system 202 is embedded in the operating system kernel 204. Since the 
FAT file system is integrated into the system kernel, it is difficult to modify. Furthermore, if additional file 
systems are required, the operating system kernel 204 must be rewritten to accommodate them. 

The present invention overcomes the above mentioned problems with the system architecture shown in 
Figure 2B. In the system 100, the OS/2 kernel 252 also includes the FAT file system 202 embedded 
therein. However, the present invention provides a method and means for dynamically attaching file system 
drivers 254, 256, 258 which are external to the operating system kernel 252. While the system 250 is shown 
with three installable file system drivers, the present invention is adapted to include a virtually unlimited 
number of file system drivers. 

An installable file system driver (FSD) is analogous in many ways to a device driver. An FSD resides on 
the disk in a file that is structured like a dynamic-link library (DLL), typically with a SYS or IFS extension, 
and is loaded during system initialization by IFS = statements in the CONFIG.SYS file. IFS= directives are 
processed in the order they are encountered and are also sensitive to the order of DEVICE = statements for 
device drivers. This allows a user to load a device driver for a nonstandard device, load a file system driver 
from a volume on that device, and so on. Once an FSD is installed and initialized, the kernel communicates 
with it in terms of logical requests for file opens, reads, writes, seeks, closes, and so on. The FSD translates 
these requests using control structures and tables found on the volume itself into requests for sector reads 
and writes for which it can call special kernel entry points called File System Helpers (FsHips). The kernel 
passes the demands for sector I/O to the appropriate device driver and returns the results to the FSD. 

The procedure used by the operating system to associate volumes with FSDs is referred to as dynamic 
volume mounting and operates as follows. Whenever a volume is first accessed, or after it has been locked 
for direct access and then unlocked (for example, by a FORMAT operation), the operating system kernel 
presents identifying information from the volume to each of the FSDs in seriatum until an FSD recognizes 
the information. When an FSD claims the volume, the volume is mounted and all subsequent file I/O 
requests for the volume are routed to the FSD which claimed the volume. 

This arrangement provides several advantages over the prior art. For example, if uncertain media is 
presented to the computer system, the computer system may scan the available file system drivers to 
locate a file system driver which recognizes the media thus providing for automatic mapping of file system 
driver to media. Furthermore, file system drivers may be updated without requiring a modification of the 
operating system kernel. In addition, as new types of peripheral devices are developed, appropriate file 
system drivers may be added to the operating system without disturbing existing system software. 

A more detailed diagram of the system 100 is shown in Figure 3. The system 100 includes an operating 


70 


15 


20 


25 


30 


35 


40 


45 


50 


55 


EP 0 415 346 A2 


system kernel 252 which facilitates communication between an application program 302 and data storage 
devices such as disk device 304. The system 100 includes a device driver 306 which works in conjunction 
with a file system driver 254-258. While the system 100 is shown as including a single peripheral device 
304, the present invention is adapted for use with any number of logical or physical peripheral devices. 

in operation, the application program 302 issues logical file requests to the operating system kernel 252 
by calling the entry points for the desired function. These functions may include requests to open files 
(DosOpen), to read files (DosRead), to write files (DosWrite), etc. The operating system kernel 252 passes 
these requests to the appropriate file system driver 254-258 for the particular volume holding the file. The 
appropriate installable file system driver then translates the logical file request into requests for reads or 
writes of logical sectors of the designated media and calls an operating system kernel file system helper 
308 to pass these requests to the appropriate device driver 306. File system helpers are discussed in more 
detail below. The disk driver 306 transforms the logical sector requests from the operating system kernel 
into requests for specific physical units: cylinders, heads and sectors of the media, and issues commands 
to the disk device to transfer data between disk media and random access memory 310. 

The mapping of physical devices into particular file systems is discussed in further detail below. In the 
MS-DOS environment, floppy disks are referred to as volumes. Fixed disks (or hard disks) may be 
partitioned into multiple volumes. This terminology applies to the present invention as well. Briefly, 
whenever the system 100 is first booted, whenever a volume is first accessed, or whenever the system 
determines uncertain media is present in disk device 304, the system examines the first file system driver 
in a linked list of file system drivers. If the file system driver recognizes the volume loaded in the disk 
device, the file system driver is mounted. Otherwise, the system sequentially polls the available file system 
drivers until a file system driver which recognizes the media is located. If no installable file system driver is 
found which recognizes the media of interest, a default file system driver is mounted. In the preferred 
practice of the present invention, the default file system is the FAT file system mentioned above. 

Uncertain media may be detected in several ways. Many disk devices are provided with a mechanical 
latch mechanism which is exercised when a disk is ejected or installed in the disk device. The latch 
mechanism typically functions such that the next operation on the drive will indicate that the door has been 
opened. When the device driver receives this indication, ERROR_UNCERTAIN_ MEDIA is returned to the 
operating system. In systems without mechanical latch mechanisms, it is assumed that media cannot be 
changed in less than a predetermined time interval. In the preferred practice of the present invention, this 
interval is assumed to be two seconds. Thus if a particular volume has not been accessed for more than the 
predetermined interval, the media is presumed to be uncertain. 

Figure 4 is a diagram of the disk format of the FAT file system. The FAT file system has been used 
with the MS-DOS operating system since its inception. A detailed description of the FAT file system may 
be found in Duncan, "Advance MS DOS Programming", Microsoft Press, 1986, 1988. A brief description of 
the FAT file system follows. The FAT file system revolves around the File Allocation Table. Each logical 
volume is associated with its own FAT, which serves two important functions: it contains the allocation 
information for each file on the volume in the form of linked lists of allocation units and it indicates which 
allocation units are free for assignment to a file that is being created or extended. 

When a disk is formatted in accordance with the FAT file system, a boot sector is written in sector zero. 
This is followed by one or more file allocation tables. The file allocation tables are followed by a root 
directory. The root directory is followed by the volume files. The boot sector contains various descriptive 
information about the volume in an area referred to as the boot parameter block or BPB, information such 
as a drive number and a volume I.D. as well as a bootstrap routine. 

The file allocation table is divided into fields that correspond directly to the assignable clusters on a 
disk (clusters are power-of-2 multiples of sectors). These fields are typically 16 bits wide. The first two 
fields in the FAT are reserved. The first reserved FAT entry contains a copy of a media descriptor byte 
which is also found in the BPB. The remaining reserved fields contain OFFH. The remaining FAT entries 
describe the use of their corresponding disk clusters. Each file’s entry in a directory contains the number of 
the first cluster assigned to that file, which is used as an entry point into the FAT. From the entry point on, 
each FAT siot contains the number of the next cluster in the file, until a last-cluster mark is encountered. 
The FAT file system also provides for the option of maintaining a duplicate of the first file allocation table 
which may be used if access to a sector in the FAT fails due to a read error, etc. 

Following the file allocation tables, is the root directory. The root directory contains 32 byte entries that 
describe files, other directories , and an optional volume label. 

The remainder of the volume after the root directory is known as the files area which may be viewed as 
pools of clusters, each containing one or more logical sectors. Each cluster has a corresponding entry in 
the FAT that describes its current use: available, reserved, assigned to a file, or unusable. 
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The FAT file system provides excellent performance with volumes which are less than 1 Mb. However, 
as volumes increase in size over 1 Mb, the performance of the FAT file system quickly degrades. This has 
become an increasingly severe problem as the size of readily available hard disks is rapidly increasing. 

When volumes are less than 1 Mb, the FAT is small enough to be retained in random access memory 
at all times, thus allowing very fast random access to any part of a file. When applied to hard disks or fixed 
disks, however, the FAT becomes too large to hold in memory and must be paged into memory in pieces. 
This results in many superfluous disk head movements, thus degrading system throughput. In addition, 
since information about disk free space is dispersed across many sectors of FAT, it is impractical to 
allocate file space contiguously, and files become fragmented, further degrading system throughput. 
Furthermore, the use of relatively large clusters on hard disks results in much wasted space. 

Figures 5A-5H are a series of diagrams showing the disk format of one instance of an installable file 
system. This file system is referred to as the high performance file system (HPFS). The high performance 
file system of the present invention eliminates the above-mentioned problems with the FAT file system and 
provides superior performance with all types of disk media. Referring now to Figure 5A, HPFS volumes can 
exist on a fixed disk along side of previously defined FAT partition types. HPFS volumes use a sector size 
of 512 bytes and have a maximum size of 2199 Gb (2° sectors). While primarily designed for use with 
fixed disks, HPFS is compatible with virtually any type of disk media. 

An HPFS voiume is required to have very few fixed structures. Sectors 0-15 of a volume (8Kb) are 
allocated to the BootBlock 502 and contain a volume name field 504, a 32-bit volume ID field, a BIOS 
parameter block 508, and a disk bootstrap program 510. The disk bootstrap program 510 can be used in a 
restricted mode to locate and read operating system files wherever they may be found. 

The BootBlock 502 is followed by a SuperBlock 512 and a SpareBlock 514. The SuperBlock 514 is only 
modified by disk maintenance utilities. It contains pointers 516 which point to free space bitmaps, a bad 
block list 518, a pointer 520 which points to a directory block band, and a pointer 522 which points to the 
root directory. It also contains a date field 524 which includes the date the volume was jast checked and 
repaired with CHKDSK. CHKDSK is a well known OS/2 disk utility for detecting and cataloging bad portions 
of a disk. 

The SpareBlock 514 contains various flags and pointers which will be further discussed below. It is 
modified as the system executes. 

The remainder of the volume is divided into 8Mb bands, e.g. bands 516-522 which are used for storing 
files. While Figure 5A shows four 8 Mb bands, HPFS provides for a very large number of bands. Each band 
is provided with its own free space bitmap, see e.g. bitmaps 524-534. Each bit in the freespace bitmaps 
represents a sector. A bit is 0 if the sector is in use and 1 of the sector is available. The bitmaps are 
located at the head or tail of a band so that two bitmaps are adjacent between alternate bands. This allows 
the maximum contiguous free space that can be allocated to a file to be 16 Mb although the bitmap 
bandsize may be modified to accommodate files of virtually any size. One band, located at or towards the 
seek center of the disk, is called the directory block band and receives special treatment as will be further 
discussed below. 

Every file or directory on an HPFS volume is anchored on a fundamental file system object called an 
Fnode which is shown in Figures 5B-5C. The Fnode 530 is the first sector allocated to a file or directory, 
and is pointed to by field 522 in the Superblock 504. Each Fnode occupies a single sector and contains 
control and access information field 540 used internally by the file system, an area 542 for storing extended 
attributes (EA) and access control lists (ACLS), a field 544 if indicating the length and the first 15 characters 
of the name of the associated file or directory, and an allocation structure 546 as shown in Figure 5B. An 
Fnode is always stored near the file or directory that it represents. 

The allocation structure 546 shown in Figure 5C takes several forms, depending on the size and degree 
of continuity of the file directory. The HPFS of the present invention views a file as a collection of one or 
more runs or extents of one or more contiguous sectors. Each run is symbolized by a pair of double-words: 
a 32- bit starting sector number and a 32-bit length in sectors (this is referred to as run length encoding). 
From an application programs point of view, the extents are invisible; the file appears as a seamless stream 
of bytes. 

The space reserved for allocation information in an Fnode can hold pointers to as many as eight runs of 
sectors of up to 16 Mb each. Reasonably small files of highly contiguous size can, therefore, be completely 
described within the Fnode. 

The HPFS employs a new method to represent the location of files that are too large or too fragmented 
for the Fnode and consist of more than eight runs. The Fnode's allocation becomes the root for a B+ tree 
of allocation sectors, which in turn contain the actual pointers to the file's sector runs as shown in Figure 
5D. The concept of B+ trees and B- trees is discussed in detail below. The Fnode’s root has room for 12 
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elements. Each allocation sector can contain, in addition to various control information, as many as 40 
pointers to sector runs. Therefore, a two level allocation B+ Tree can describe a file of 480(12"40) sector 
runs, with a theoretical maximum size of 7.68 Gb (12*40*16 Mb) in the preferred practice of the present 
invention. , 

In the unlikely event that a two-level B+ Tree is not sufficient to describe a highly fragmented file, the 
HPFS file system introduces additional levels in the tree as required. Allocation sectors in the intermediate 
levels can hold as many as 60 internal (nonterminal) B+ tree nodes, which means that the descriptive 
ability of this structure rapidly grows to numbers that are extremely large. For example, a three-level 
allocation B+ Tree can describe as many as 28,800 (12°60"40) sector runs. 

Run-length encoding and B+ Trees of allocation sectors are a memory efficient way to specify a file's 
size and location and offer several significant advantages over the prior art. Translating a logical file offset 
into a sector number is extremely fast: the file system merely traverses the list (or B+ Tree of lists) of run 
pointers, summing up run sizes until the correct range is found. It can then identify the sector within the run 
with a simple calculation. Run-length encoding also makes it trivial to extend the file logically if the newly 
assigned sector is contiguous with the file's previous last sector; the file system merely increments the size 
double-word of the file's last run pointer and clears the sector's bit in the appropriate freespace bitmap. 

Directories, like files, are anchored on Fnodes. A pointer 522 to the Fnode for the root directory is found 
in the SuperBlock 512. Figure 5E shows the directory structure of the present invention wherein a directory 
Fnode 550 is shown. The Fnodes for directories other than the root are reached through subdirectory 
entries in their parent directories. 

Directories are built up from 2 Kb directory blocks, which are allocated as four consecutive sectors on 
the disk and can grow to any size. See e.g. directory blocks 552, 554, 556. The file system attempts to 
allocate directory blocks in the directory band, which is located at or near the seek center of the disk. Once 
the directory band is full, the directory blocks are allocated wherever space is available. 

Each 2 Kb directory biock may contain from one to many directory entries. See e.g. entries 558-568. A 
directory entry contains several fields, including a field 570 for time and date stamps, a field 572 which 
contains an Fnode pointer, a usage count field 574 for use by disk maintenance programs (which are well 
known), a field 576 which contains the length of the file or directory name, a field 578 for the name itself, 
and a field 580 which contains B- Tree pointer, as shown in Figure 5E. Each directory entry begins with a 
word 582 that contains the length of the entry. This provides for a variable amount of flex space at the end 
of each entry, which can be used by special versions of the file system and allows the directory block to be 
traversed very quickly. 

The number of entries in a directory block varies with the length of names. If the average filename 
length is 13 characters, an average directory block will hold approximately 40 entries. The entries in a 
directory block are sorted by the binary lexical order of their name fields. The last entry is a dummy record 
that marks the end of the block. 

When a directory gets too large to be stored in one biock, it increases in size by the addition of 2 Kb 
blocks that are organized as a B- Tree. When searching for a specific name, the file system traverses a 
directory block until it either finds a match or finds a name that is lexically greater than the target. In the 
latter case, the file system extracts the B- Tree pointer from the entry. If this pointer points to nowhere, the 
search failed; otherwise, the file system follows the pointer to the next pointer to the next directory block in 
the tree and continues the search. 

Assuming 40 entries per block, a two-level tree of directory blocks can hold 1640 directory entries and 
a three level tree can hold 65,640 entries. In other words, a particular file can be found (or shown not to 
exist) in a typical directory of 65,640 files with a maximum of three disk accesses. The actual number of 
disks accesses depends on cache contents and the location of the file's name in the directory block B- 
Tree. This presents a vast improvement over the FAT file system where in a worst case, 4,000 sectors 
would have to be read to establish whether a file was present in a directory containing the same number of 
files. 

The B- Tree directory structure of the HPFS has interesting implications beyond its effect on open and 
find operations. A file creation, renaming, or deletion may result in a cascade of complex operations, as 
directory blocks are added or freed or names are moved from one block to the other to keep the tree 
balanced. In fact, a rename operation could fail for lack of disk space even though the file itself is not 
growing. In order to avoid this problem, the HPFS reserves a small pool of free blocks that can be drawn 
from in a directory emergency; a pointer to this pool is preferably stored in the SpareBlock. 

File attributes are information about a file that is maintained by the operating system outside the file's 
overt storage area. 

The HPFS of the present invention supports Extended Attributes (EAs) taking the form 
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name = value 

except that the value portion can be either a null-terminated (ASCIIZ) string or binary data. In the preferred 
practice of the present invention, each file or directory can have a maximum of 64 Kb of EAs attached to it 
although this limit may be readily modified. 

The storage method for EAs can vary. If the EAs associated with a given file or directory are small 
enough, they will be stored in the Fnode. If the total size of the EAs is too large, they are stored outside the 
Fnode in sector runs, and a B+ Tree of allocation sectors is created to describe the runs. If a single EA 
gets too large, it may be pushed outside the Fnode into a B+ Tree of its own. 

The present invention provides an improvement to the OS/2 kernel API functions DosQFilelnfo and 
DosSetFilelnfo that allow application programs to manipulate extended attributes for files. The present 
invention further provides two new functions DOSQPathInfo and DosSetPathinfo which may be used to read 
or write the EAs associated with arbitrary pathnames. An application program may either request the value 
of a specific EA (supplying a name to be matched) or can obtain all of the EAs for the file or directory at 
once. The support of EAs facilitates the use of object oriented application programming. Information of 
almost any type can be stored in EAs, ranging from the name of the application that owns the file, names of 
dependent files, icons, and executable code. 

The HPFS attacks potential bottlenecks in disk throughput at multiple levels. It uses advanced data 
structures, contiguous sector allocation, intelligent caching, read-ahead, and deferred writes in order to 
boost performance. First, the HPFS maiches its data structures to the task at hand: sophisticated data 
structures (B- Trees and B+ Trees) for fast random access to filenames, directory names, and lists of 
sectors allocated to files or directories, and simple compact data structures (bitmaps) for locating chunks of 
free space of the appropriate size. The routines that manipulate these data structures are preferably written 
in assembly language. 

The main objective of the HPFS is to assign consecutive sectors to files wnenever possible. The time 
required to move the disk's read/write head from one track to another far outweighs the other possible 
delays, so the HPFS avoids or minimizes such head movemenis by allocating file space contiguously and 
by keeping contro! structures such as Fnodes and freespace bitmaps near the things they control. Highly 
contiguous files also help the file system make fewer requests of the disk driver for more sectors at a time, 
allow the disk driver to exploit the multisector transfer capabilities of the disk controller, and reduce the 
number of disk completion interrupts that must be serviced. 

Keeping files from becoming fragmented in a multitasking operating system in which many files are 
being updated concurrently is a feature not found in the prior art. One strategy the HPFS uses is to scatter 
newly created files across the disk in separate bands, if possible, so that the sectors allocated to the files as 
they are extended will not be interleaved. Another strategy is to preallocate 4Kb of contiguous space to the 
file each time it must be extended and give return any excess when the file is closed. 

if an application knows the ultimate size of a new file in advance, it may assist the HPFS by specifying 
an initial file allocation when it creates a file. The system then searches ail the free space bitmaps to find a 
run of consecutive sectors large enough to hold the file. That failing, it searches for two rounds that are half 
the size of the file, and so on. 

The HPFS relies on several different kinds of caching to minimize the number of physical disk transfers 
it requests. It caches sectors, as did the FAT file system. But unlike the FAT file system, the HPFS 
manages very large caches efficiently and adjusts sector caching on a per-handle basis to the manner in 
which a file is used. The HPFS also caches pathnames and directories, transforming disk directory entries 
in to an even more compact and efficient in memory representation. 

Another technique that the HPFS uses to improve performance is to preread data it believes the 
program is likely to need. For example, when a file is opened, the file system will preread and cache the 
Fnode and the first few sectors of the file's contents. If the file is an executable program or the history 
information in the file's Fnode shows that an open operation has typically been followed by an immediate 
sequential read of the entire file, the file system will preread and cache much more of the file’s contents. 
When a program issues relatively small read requests, the file system always fetches data from the file in 
2Kb chunks and caches the excess, allowing most read operations to be satisfied from the cache. 

The HPFS of the present invention relies heavily on lazy writes based on OS.2 multitasking capabilities 
(sometimes called deferred writes or write behind) to improve performance. For example, when a program 
requests a disk write, the data is placed in the cache and the cache buffer is flagged as dirty (that is. 
inconsistent with the state of the data on disk). When the disk becomes idle or the cache becomes 
saturated with dirty buffers, the file system uses a captive thread from a daemon process to write the 
buffers to disk, starting with the oldest data. Captive threads and daemon processes are described in a 
series of texts: Hastings, et al. “Microsoft OS/2 Programmers Reference”, Microsoft Press, 1989. 
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In general, lazy writes mean that programs run faster because their read requests will typically not be 
stalled waiting for a write request to complete. For programs that repeatedly read, modify, and write a smail 
working set of records, it also means that many unnecessary or redundant physical disk writes may be 
avoided. Lazy writes have their certain dangers, and therefore, the present invention provides that a 
program can defeat them on a per-handle basis by setting the write-through flag in the OpenMode 
parameter for DosOPen, or it can commit data to disk on a per-handle basis with the DosBufReset function. 
Both DosOpen and DosBufReset functions are available in current versions of OS/2. 

The extensive use of lazy writes makes it imperative for the HPFS to be able to recover gracefully from 
write errors under any but the most dire circumstances. For example, by the time a write is known to have 
failed, the application has long since gone on its way under the illusion that it has safely shipped the data 
into disk storage. The errors may be detected by hardware (such as a "sector not found” error returned by 
the disk adapter), or they may be detected by the disk driver in spite of the hardware during a read-after- 
write verification of the data. 

The primary mechanism for handling write errors is referred to as a hotfix. When an error is detected, 
the file system takes a free block out of a reserved hotfix pool, writes the data to that block, and updates 
the hotfix map. (The hotfix map is simply a series of pairs of doublewords, with each pair containing the 
number of a bad sector associated with the number of its hotfix replacement.) A copy of the hotfix map is 
then written to the SpareBlock, and a warning message is displayed to let the user know that there is a 
problem with the disk device. 

Each time the file system requests a sector read or write from the disk driver, it scans the hotfix map 
and replaces any bad sector numbers with the corresponding good sector holding the actual data. 

One of CHKDSK's duties is to empty the hotfix map. For each replacement biock on the hotfix map, it 
allocates a new sector that is in a favorable location for the file that owns the data, moves the data from the 
hotfix block to the newly allocated sector, and updates the file's allocation information (which may involve 
rebalancing allocation trees and other elaborate operations). It then adds the bad sector to the bad block 
list, releases the replacement sector back to the hotfix pool, deletes the hotfix entry from the hotfix map, 
and writes the updated hotfix map to the SpareBlock. 

The HPFS maintains a Dirty FS flag in the SpareBlock of each HPFS volume. The flag is cleared when 
all files on the volume have been closed and ail dirty buffers in the cache have been written out or, in the 
case of the boot volume, when Shutdown has been selected and has completed its work. 

During the OS/2 boot sequence, the file system inspects the DirtyFS flag on each HPFS volume and, if 
the flag is set, will not allow further access to that volume until CHKDSK has been run. If the DirtyFS flag is 
set on the boot volume, the system will run CHKDSK automatically. 

In the event of a truly major catastrophe, such as loss of the SuperBlock or the root directory, the HPFS 
is designed to give data recovery the best possible chance of success. Nearly every type of crucial file 
object, including Fnodes, allocations sectors, and directory blocks, is doubly linked to both its parent and its 
children and contains a unique 32-bit signature. Fnodes also contain the initial portion of the name of their 
file or directory. Consequently, SHODS can rebuild an entire volume by methodically scanning the disk for 
Fnodes, allocations sectors, and directory blocks, using them to reconstruct the files and directories and 
finally regenerating the freespace bitmaps. 

As mentioned above, the present invention employs B+ trees and B- trees (binary trees) for logically 
ordering files and directories. Binary trees are a technique for imposing a logical ordering on a collection of 
data items by means of pointers, without regard to the physical order of the data. 

Referring now to Figures 5F, in a simple binary tree, each node contains some data, including a key 
value that determines the node's logical position in the tree, as weil as pointers to the node's left and right 
subtrees. The node that begins the tree is known as the root; the nodes that sit at the ends of the tree's 
branches are sometime called the leaves. 

To find a particular piece of data, the binary tree is traversed from the root. At each node, the desired 
key is compared with the node's key; if they don't match, one branch of the node's subtree or another is 
selected based on whether the desired key is less than or grater than the node's key. This process 
continues until a match is found or an empty subtree is encountered as shown in Figure 5F. 

Such simple binary trees, although easy to understand and implement, have disadvantages in practice. 
If keys are not well distributed or are added to the tree in a non-random fashion, the tree can become quite 
asymmetric, leading to wide variations in tree traversal time. 

In order to make access times uniform, many programmers prefer a particular type of balanced tree 
known as a B- Tree as shown in Figure 5. The important points about a B- Tree are that the data is stored 
in all nodes, more than one data item might be stored in a node, and ali of the branches of the tree are of 
identical length. 
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The worst-case behavior of a B- Tree is predictable and much better than that of a simple binary tree, 
but the maintenance of a B- Tree is correspondingly more complex. Adding a new data item, changing a 
key vaiue, or deleting a data item may result in the he splitting or merging of a node, which in turn forces a 
cascade of other operations on the tree to rebalance it. 

As shown in Figure 5G, a B+ Tree is a specialized form of B- Tree that has two types of nodes: 
internal, which only point to other nodes, and external, which contain the actual data. 

The advantage of a B+ Tree over a B- Tree is that the internal nodes of the B+ Tree can hold many 
more decision values than the intermediate-level nodes of a B- Tree, so the fan out of the tree is faster and 
the average length of a branch is shorter. This compensates for the fact that a B+ Tree branch must be 
followed to its end to find the necessary data, whereas in a B- Tree the data may be discovered at an 
intermediate node or even at the root. 

The present invention comprises an improvement to the OS/2 operating system and may be imple- 
mented with many of the utilities and subroutines available in current versions of OS/2. While primarily 
intended for use with the OS/2 operating system, the principles of the present invention may be applied to 
virtually any computer operating system. With the exception of the new utilities and subroutines described 
herein, all other utilities and subroutines are currently available and well known. For a detailed description of 
the OS/2 operating system refer to the OS/2 Programmer's Reference texts described above. Volume 
Management in the improved OS/2 operating system of the present invention is responsible for the same 
duties it performed in previous versions of OS/2 such as detecting when the wrong volume is inserted in the 
drive, detecting when a volume has been removed, generating new information on new media that has been 
placed in the drive via the Volume Parameter Biock (VPB), communicating with the appropriate device 
drivers, providing the system with device information needed to access new inserted media, interfacing with 
the Buffer and CDS mechanisms, and informing the system of changes to a specific volume. 

In previous versions of OS/2, there was only one file system. The present invention provides for 
multiple file systems in a unified environment. The volume manager determines which file system should 
have access to a particular volume, provides mechanisms that will allow file system drivers (FSDs) to 
manage their resources for a particular volume, and provides the same support for all FSDs provided in the 
past for managing volumes. The present invention relies on existing well-known OS2 cails as well as 
several new functions described herein. A complete description of the installable file system of the present 
invention is set forth in Appendix | which is attached hereto in the form of microfiche and is herein 
incorporated by reference. 

The present invention contemplates the use of MOUNT and UNMOUNT processes to facilitate the 
identification and loading of the correct file system driver for individual volumes. 

The MOUNT Process gets initiated by several different events: 

1. The first access to a voiume. 

2. Whenever the volume in a drive becomes uncertain. (This usually means the user put a new medium 
in the drive.) 

3 Whenever access to a volume that is not in the drive is requested. 

Input to the MOUNT process is a pointer to a drive parameter block (DPB) which ts used to do | 0 to 
the device driver and to store the handie to the VPB for the volume currently believed to be in the drive. A 
mount operation updates this. A local VPB is allocated on a stack and initialized with the DPB pointer. 

Referring now to Figure 6, the MOUNT process 600 begins by reading logical sector 0 of the media as 
indicated by item 602. Any errors encountered from the device driver are ignored because it is possible that 
different types of media (i.e Optical Disk or CD-ROM) may have track 0 unreadable. Before reading logical 
sector 0 the temporary mount buffer is initialized to zeros. The Volume label text field is initialized to 
"UNLABELED". Sector 0 is checked to determine whether the format is recognized by comparing signature 
byte for a special value (41). If the format is not recognized, the information pertinent to the VPB is filled in 
on the stack (i.e 32 Bit Volume Serial Number). 

A BUILDBPB cail is then issued by item 604 to the device driver specified in the DPB. BUILDBPB is a 
procedure exported by a device drivers. A detailed description of the BUILDBPB procedure is set forth in 
Appendix |. BUILDBPB is called to learn the physical parameters of the device (bytes per sector, sectors 
per track, and the like.) The device driver is passed a pointer to the buffer that contains information it can 
use to determine the physical parameters of the volume. For most drivers this is sector 0, for some very old 
ones it is the first sector of the FAT. If the device is not able to interpret the data read from Sector 0 (for 
example, the floppy in question is not FAT, so the FAT ID byte is meaningless) the device returns a 
minimal BPB, adequate to allow the kernel and FSDs to do necessary i/O to completely identify the volume. 

The relevant fields from the previousiy created BPB are copied into the Local VPB on the stack (i.e 
Sectors/track, NumberofHeads, Total Sectors, Sector Size). A new VPB is allocated and information from 
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the Local VPB is copied into it. The present invention then enters loop 606 to poll each FSD by calling the 
FS MOUNT (fiag=0) entry point with the handle of newly created VPB, a pointer to logical sector 0, and 
pointers to VPB file system independent and dependent areas of the VPB as indicated by item 608. The 
FSD may call FSH_ DoVollO to read other sectors from the volume (It must allocate its own buffer). If the 
FSD returns ERROR_UNCERTAIN_ MEDIA, the error is returned and the process is restarted as indicated 
by decision 610. If the FSD supports boot sectors, it may check the file system name field in the boot 
sector to determine whether it recognizes it. If the FSD does not support boot sectors I/O to the device is 
performed to determine if the FSD recognizes the volume. Once an FSD has recognized the volume it 
updates the relevant fields in the VPB file system independent and dependent areas as indicated by item 
612. The VPB file system independent and dependent areas are discussed in more detail in conjunction 
with Figure 7. At-this time the FSD issues a FS Helper (FSH) function to determine whether the new volume 
is the same as any of the other volumes that the present invention manages. This FS Helper returns 
pointers to the file system independent and dependent areas. The FSD then copies information from the 
newly created VPB to old VPB as indicated by item 614. The newly created VPB is destroyed after the 
MOUNT call. The FSD then performs any cleanup work on the old VPB Suen as invalidating any buffers 
since the volume may have been removed from the drive. 

Once an FSD has recognized the volume, the present invention eliminates the new VPB if a match is 
found in the list. Otherwise, the VPB is linked into a list of mounted FSDs. If no FSDs are recognized, the 
VPB is freed and the FAT file system is mounted as indicated by decision 614 and item 616. 

When a new volume is inserted into a drive and the old volume has no more kernel references to the 
old volume the present invention issues a FS_ MOUNT (flag =2) to the FSD so that resources allocated to 
that volume may be de-allocated. 

When the present invention detects that a newly inserted volume is different than the last volume in the 
drive a FS_ MOUNT (flag = 1) call is issued to the FSD so that any cleanup type work such as buffer 
invalidation on the removed volume may be performed. if there are no more kernel references to the 
volume, a FS MOUNT (flag = 2, UNMOUNT) will follow. If the newly inserted volume is the same as the 
last seen volume in the drive, this cail is not issued. 

The present invention contemplates the use of an efficient mechanism to utilize existing kernel 
resources for functions required by an FSD. Specifically, if an FSD requires a function existing within the 
kernel, the FSD issues a file system helper (FSH) call which invokes the file system heiper. The called FSH 
then returns the requested information. A brief summary of file system helpers is set forth below. While the 
summary set forth below lists several important file system helpers, it is contemplated that additional file 
system helpers will be provided as required. File system helpers are discussed in detail in Appendix I. 


File System Helpers: 








FSH _GETVOLPARM - On many FS calls, the handle to the VPB is passed to the FSD and it is often 
necessary for the FSD to access the file system independent and dependent areas of the VPB. This helper 
provides that service. 

FSH _DOVOLIO - When an FSD needs to perform I/O to a specified volume it uses this helper to insure 
that the requested volume is indeed in the drive, to cail the appropriate device driver and to handle hard 
errors. This helper may be used at all times within the FSD. When called within the scope of a 
FS_ MOUNT call, it applies to the volume in the drive. However, since volume recognition is not complete 
until the FSD returns to the FS MOUNT call, the FSD must take care when = an 
ERROR_UNCERTAIN_ MEDIA is returned. This indicates that the media has gone uncertain while trying to 
identify the media in the drive. This may indicate that the volume that the FSD was trying to recognize was 
removed. In this case, the FSD releases any resources attached to the hVPB passed in the FS_ MOUNT 
call and ERROR_UNCERTAIN_ MEDIA is returned to the FS MOUNT call. This directs the volume 
tracking logic to restart the mount process. 

FSH DUPLICATEVPB - During a FS_ MOUNT call the input VPB may be the same volume as one of 
the other volumes being managed. It is the responsibility of the FSD generate up-to-date information on the 
new volume and copy that information to the older duplicate VPB. This helper determines if an older 
duplicate VPB exists and if it does, pointers to the file system independent and dependent areas of the 
older duplicate VPB will be returned so that these areas can be updated by the FSD. The FSD then 
performs any cleanup work on the old volume since the volume may have been removed. 

As mentioned above, the present invention contempiates the use of pre-existing OS/2 resources 
whenever possibile. The listing below is a summary of the hierarchy of functions invoked during the 
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operation of the present invention. 


DoVolIoO 


Be 
ge WhatVolume 
Ve sed: ProbeChange 
be rey ResetMedia 
beds GennvVPB 
p ies Aeon Seat LockVBuf 
Ledwowe ReadBoot 
gL Ca ae BuildBPB 
1 ee es Se FSMountVolume 
1.1.3.4.1 Bmp_Get 
1.1.3.4.2 VPBCopy 
Ledws saa VPBLink 
1.1.3.4.4 VPBFind 
1.1.3.4.5 VPBFree 
dw kee SetVPB 
Lod. 36 FindVID 
Léedbede? DiskIO 
1.1.3.8 CRC 

1.1.3.9 VPBFIND 

1.1.3.10 Bmp_Get 

BGs aes erage Os | VPBCopy 

a Be ewes Bea VPBLink 

g Ue Gere Pre x | UnlockvVBuf 

p ares lees Jee [| BufInvalidate (Redetermine Media) 

14223%15 FlushBuf (Redetermine Media) 

1.1.4 IncVPBRef 

Le eo DecVPBRef 

gas Ses ae | VPBFree 

i.136 ResetCurrency 

Lace6s.1 NextcDS 

1b 6a2 PointComp 

i263 BufInvalidate 

Table 1. 


The present invention is invoked whenever media becomes uncertain or whenever media is first 
accessed. The volume management function of the present invention is represented by line 1. The initial 
process is to determine what volume has been presented to the system as indicated by line 1.1. In line 
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1.1.1, ProbeChange is called to access the device driver to determine if the device driver detected a 
change in media. If a change in media was detected, ResetMedia is invoked in line 1.1.2 to instruct the 
device driver to allow I/O to the media. GenhVPB is then invoked in line 1.1.3 to generate a volume 


parameter block. This process begins with line 1.1.3.1 where LockVBuf is called to clear and serialize a 


buffer in the operating system kernel. In line 1.1.3.2, the data in the media boot sector is read into the 
operating system buffer. The system proceeds to line 1.1.3.3 wherein BuildBPB is invoked to call the disk 
driver and build a boot parameter block. FS_ Mount is then invoked in line 1.1.3.4. The first step in 
FS__Mount invokes Bmp_ Get in line 1.1.3.4.1 which is a memory management utility in the kernel which is 
called to set-up a buffer for the BPB. In line 1.1.3.4, when FSMountVolume is called, it iterates through the 
list of FSDs, calling each FSD's FS_ Mount procedure until one returns success or the end of the list is 
reached. lf an FSD returns success, in line 1.1.3.4.2, VPBCopy is called to create a temporary buffer for a 
copy of the BPB. VPBLink is then called in line 1.1.3.4.3 to link the VPB into a chain and set-up the BPB to 
point to the next VPB in the chain and io initialize the current VPB to the beginning of the list. VPBFind is 
invoked in line 1.1.3.4.4 to examine the chain of VPBs to find a VPB which possesses the same volume 
identifier as the VPB being processed. lf a duplicate VPB identifier is found, VPBfree is called in line 
1.1.3.4.5 to free the VPB under examination from the BPB if a duplicate VPB is found in the list of VPBs. 
Once FSMountVolume is complete, SetVPB is invoked in line 1.1.3.5 which sets up the appropriate fields in 
the VPB. In line 1.1.3.6, FindVID is called to find the volume identifier. DiskIO is invoked in fine 1.1.3.7 if no 
boot block is found in sector 0 of the media to locate the BPB for the volume. If no FSD's FS_ Mount 
routine returned success, then inline code which is logically equivalent to the FS__ Mount procedure for the 
(resident) FAT file system is called. In line 1.1.3.8 CRC is called to checksum the first directory of old FAT 
volumes, to generate a unique volume serial number for volume that do not have a serial number in their 
boot sectors. The functions listed in lines 1.1.3.9 -1.1.3.13 are then invoked to generate a new volume 
identifier and free the volume identifier buffer. In line 1.1.2.14, Buflnvalidate is invoked to invalidate ail data 
in the buffer if the media has changed since the process began. If so, FlushBuf is called in line 1.1.3.15 to 
flush the buffers for the new media. 

If a preexisting VPB for the volume was not found, IncVPBReF in line 1.1.4 is invoked to increment a 
reference counter for the current VPB which is used to record whether the volume of interest is still open to 
the operating system kernel. In line 1.1.5, DecVPBRef is invoked to decrement the reference counter for a 
previous VPB. If the reference counter is decremented to zero, VPBFree is invoked in line 1.1.5.1 to free 
the VPB. ResetCurrency is called in line 1.1.6 to mark position data in current directory structures as 
invalid. NextCDS (1.1.6.1) and PointComp (1.1.6.2) are internal routines used to enumerate current directory 
structures (CDSs). In line 1.1.6.3 Buflnvalidate is called to remove (now stale) VPB references from a file 
system buffer pool. 

As mentioned above, a VPB is used by the system to store information about a particular volume that is 
in use in the system. A volume is defined as a medium in a block device and the information on the 
medium differentiates it from every other volume. 

VPBs are kept in a segment as BMP. Therefore, the system needs only track the records that are in 
use, and takes manages the free list. 

Every time a new volume is encountered, i.e a VPB built for a volume does not match any of the VPBs 
already in the system, a new entry is allocated in the BMP managed segment and is filled in with the 
relevant data from the medium. Every time the system is finished with a VPB, i.e. its refcount goes to zero, 
the entry in the BMP managed segment is freed, BMP tracks this freed storage for reuse. The structures 
used by the functions of Table | are set forth below. 

A VPB Is divided into three parts: 

1. the kernel! private part, used to keep information the kernel needs to manage the VPB (reference 
counts, for example). This is private to the kernel, meaning that FSDs never access or modify it. 

2. the file system independent part, used by all file systems and independent of any particular file 
system. This is passed to an installable file system (IFS) for certain file system (FS) calls, and 

3. a part that is specific to the file system that is using the VPB. This is set out as a "work area" that the 
file system can use as required. This is passed to the IFS for certain FS calls. The layout of the VPB is 
shown in Figure 7. 

The following structure defines the file system independent part of the VPB. This structure is used by 
ail file systems irrespective of the type of file system. 
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vpbfsi STRUC 

vpi_ID DO i" , 32 bit unique ID of file 

vpi_pOPB DOD ? ; Drive volume is in 

vpi_cbSector DW ? ; Size of physical sector in bytes 
vpi_totsec DD cs ; Total number of sectors on medium 
vpi_trksec DW ? ; Sectors per track on medium 
vpi_nhead OW ? ; Number of heads in device 

vpi text DB VPBTEXTLEN DUP (?) ; printable ID for users 
vpbtsi ENDS 


The following structure defines the file system dependent part of the VPB. This structure is used by file 
systems as they see fit. 


vpbfsd STRUC 
vpd work DB VPOWORKAREASIZE DUP (7) 
vpbisd ENDS 


The following structure defines the structure of the volume parameter block VPB). 


vpb STRUC 

Fields used by kernel for all file systems 

vpb_flink OW ? ; handle of forward link 

vpb_ blink DW SCs? ; handie of back link 

vpb_!Osector DD ? : sector number of ID 
vpb_ref_count OW ? ; count of objects that point to VPB 
vpb_search_count DW ? ; count of searches that point to VPB 
vpb first_access DB ? : This is initialized to -1 to force a media 
vpb_ signature OW ? ; Signature which specifies VPB validity 
vpb_flags O08 : ; flags 

? ; Pointer to the file system control block (FSC). 


vpb_FSC OD 


The following fields are used for file system dependent work. 


vpb_fsd OB SIZE vpbfsd DUP (7) 


The following fields are used for file system independent work. 


vpb _fsi DB SIZE vpbfsi DUP (7?) 
vpb ENDS 


The following structure is used by FSH__GETVOLPARM - which is used to get VPB data from VPB handle. 


ENTRY push word hVPB (1 word) 
push dword ptr to file system ind. (2 word) 
push dword ptr to file system dep. (2 word) 
call FSHGETVOLPARM 


EXIT (ax) = return code 
0 - success 
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The following structure is used by FSH_DOVOLIO - which is used for volume-based sector-oriented 


transfers 
: ENTRY push word Operation (1 word) 

5 push word hVPB (1 word) 
push dword ptr to user transfer area (2 word) 
push dword ptr to sector count (2 word) 
push dword starting sector number (2 word) 
Cail FSHDOVOLIO 

10 

EXIT (ax) = return code 
0 - success 
15 
The following structure is used by FSH_DUPLICATEVPB - which is used to get VPB data to a duplicate 
(old) VPB. 

a ENTRY push word hVPB (1 word) 
push dword ptr to file system ind. (2 word) 
push dword ptr to file system dep. (2 word) 
call FSHGETVOLPARM 

25 

EXIT (ax) = return code 
0 - success 
me RedetermineMedia has a special set of entry parameters, as shown, below. 
ENTRY (OS;S!) point to dpb 
35 EXIT Carry clear => 
(DS:SI).hVPB is filled in with the “correct” volume 
Carry Set => 
(AX) = !/O packet status; operation was failed 
USES AX, BX, DX, Di, ES, Flags 
40 


The following calls are used for volume management intra-component interfaces. 
GenhVPB is used to determine the internal VPB in a particular drive. Any errors returned are sent to the 
user. 
45  ‘'nputs; ds;si point to DPB of interest. It and whatever volume was in it last are locked. 
Outputs; Carry clear = > ax is handle to VPB for drive 
Carry set = > operation generated an error 
zero clear = > operation was failed 
zero set = > nested uncertain media occurred 
50 
All registers may be modified 
BuildBPB is called to generate a valid BPB for an old disk; one that does not have a recognized boot 
sector. The newer disks have a KNOWN and VALID BPB in the boot sector. The buffer to the device driver 
is part of the BuildBPB call. 
ss _ Inputs; ds;si point to DPB of interest 
pVPBBuf is locked 
Outputs; carry clear = > 
ds;si points to a BPB 
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carry set = > 
(AX) = status word from device 
zero set = > nested uncertain media error 
zero reset => operation was failed 
All registers modified all except BP 
FSMountVolume checks to determine whether an IFS Driver recognizes the Volume of interest. 
FSMountVolume Loops through the FSD chain calling each FS Driver FS Mount entry point to 
determine whether the IFS recognizes the volume of interest. The loop terminatea when the first IFS 
recognizes the volume or when the loop counter for the number of FS Drivers installed in the system 
decrements to 0. 


Inputs; ds;bx point to pVPBBuf boot sector 
di offset of LocalVPB on Stack 
Outputs; di = offset to FSC If an IFS recognized the volume. 
di = -1 if no IFS driver recognized the volume 
ax = vpb handle 
Registers modified: ax,op,bx,di,es,si,ds 
VPBFree removes the VPB from the link list and Frees its block from the segment. 


ENTRY (BP) = handle to VPB 
EXIT VPB unlinked and Freed 
USES bx, bp,cx,di,ds,es 


VPBLink inserts the new VPB at the beginning of the list and adjusts the forward and backlink fields of 
new VPB and the old first VPB. 


ENTRY ES;Di = New VPB 
EXIT VPB Linked into list. 


USES OS,SI 


VPBFind scans the internal list looking for a VPB with the same Vol. ID as the input VPB. 


ENTRY DS:S! = Pointer to input VPB Vol. ID 
EXIT AX = AVPB if found 
AX = Off not found 


USES AX,BX,CX,DI.DS.ES 


VPBCopy copies a VPB from the local area to the BMP managed area and stamps VPB as valid. 


ENTRY S| = Offset of LocalVP8 on Stack 
ES:DI -> New VPB 

EXIT None 

USES AX,CX,DS,S! 


Volume management, i.e., detecting when the wrong volume is mounted and notifying the operator to 
take corrective action, is handled directly through the operating system kernel and the appropriate device 
driver. According to the principles of the present invention, each file system driver (FSD) generates a 
volume label and 32-bit volume serial number for each volume used with the system. Preferably, these are 
stored in a reserved location in logical sector zero when a volume is formatted. No particular format is 
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required to store this information. The operating system kernel calls the FSD to perform operations that 
might involve it. The FSD updates the volume parameter block (VPB) whenever the volume label or serial 
number is changed. 

When the FSD passes an I/O request to an FS helper routine the device driver passes the 32-bit 
volume serial number and the volume label (via the VPB). When the I/O is performed on a volume, The 
operating system kernel compares the requested volume serial number with the current volume serial 
number it maintains for the device. This is an in-storage test (no I/O required) performed by checking the 
Drive Parameter Block's (DPB) VPB of volume mounted in the drive. If unequal, The operating system 
kernel signals the critical error handler to eee the user to insert the volume having the serial number and 
label specified. 

When a media change is detected a drive, or the first time a drive is accessed on behalf of an 
application program interface (API) function call, the present invention determines the FSD (file system 
driver) that will be responsible for managing I/O to that volume. The present invention then allocates a VPB 
(volume parameter block) and polls the installed FSDs an FSD indicates that it does recognize the media. 
The FSDs are polled as described above. 

The FAT FSD is the last in the list of FSDs and, by recognizing all media, will act as the default FSD 
when no other FSD recognition takes place. 

According to the principles of the present invention, there are two classes of file system drivers: 

1. an FSD which uses a block device driver to do I/O to a local or remote (virtual disk) device. (This is 

referred to as a local file system), and 
2. an FSD which accesses a remote system without a block device driver This is called a remote file 
system. 

The connection between a drive letter and a remote file system is achieved through a programmatic 
interface. The DosFSAttach system call is used to create a binding between an object in the system name 
space (e.g. A drive) and an FSD. 

The connection between a pseudo-character device and a remote file system is also achieved through 
the DosFsAttach interface. The DosFsAttach interfaces comprises the DosFsAttach and DosQFsAttach calls 
which are described in detail in Appendix I. 

When a local volume is first referenced, the present invention sequentially asks each local FSD in the 
FSD chain to accept the media, via a call to each FSD's FS MOUNT entry point. If no FSD accepts the 
media then it is assigned to the default FAT file system. Any further attempt made to access an 
unrecognized media other than by FORMAT, results in an INVALID. MEDIA_FORMAT' error message. 

Once a volume has been recognized, the relationship between drive, FSD, volume serial number, and 
volume label is stored. The volume serial number and labe! are stored in the volume parameter biock, 
(VPB). The VPB is maintained by the operating system for open files (file-handie based 1/O), searches, and 
buffer references. 

Subsequent requests for a removed volume require polling the installed FSDs for volume recognition by 
calling FS_ MOUNT. The volume serial number and volume label of the VPB returned by the recognizing 
FSD and the existing VPB are compared. If the test succeeds, the FSD is given access to the volume. If the 
test fails, the operating system signals the critical error handler to prompt the user for the correct volume. 

The connection between media and VPB is saved until all open files on the volume are closed, search 
references and cache buffer references are removed. Only volume changes cause a re-determination of the 
media at the time of next access. 

Access to an operating system partition on a bootable, logically partitioned media is through the full 
operating system function set such as the function set available with the OS/2 operating system. A detailed 
description of disk partitioning design is available in the OS/2 Programmer's Reference texts described 
above. 

The present invention provides the DosQFsAttach function to identify remote devices which commu- 
nicate with the operating system through a network. 

The purpose of DosQFsAttach is to query information about an attached remote file system, a local file 
system, about a character device, or about pseudo-character device name attached to a local or remote 
FSD. 

The sequence for calling DosQFsAttach is as follows: 
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EXTRN DosQFsAttach:FAR 


PUSH ASCIIZ DeviceName __ ; Device name or ‘d:' 
PUSH WORD Ordinal ; Ordinal of entry in name list 
PUSH WORD FSAinfoLevel ; Type of attached FSD data required 
PUSH OTHER OataButfer ; Returned data buffer 
PUSH WORD DataBufferLen ; Buffer length 
PUSH DWORD 0 ; Reserved (must be zero) 
CALL DosOQFsAttach 
Where: 


DeviceName points to the drive letter followed by a colon, or points to a character or pseudo-character 
device name, or is ignored for some values of FSAlInfoLevel If DeviceName is a drive, it is an ASCIIZ string 
having the form of drive letter followed by a colon. If DeviceName is a character or pseudo-character device 
name, its format is that of an ASCIIZ string in the format of a filename in a subdirectory called which ts 
preferably designated \DEV\. 

Ordinal is an index into the list of character or pseudo-character devices, or the set of drives. Ordinal 
always starts at 1. The Ordinal position of an item in a list has no significance, Ordinal is used strictly to 
step through the list. The mapping from Ordinal to item is volatile, and may change from one call to 
DosQFsAttach to the next. : 

FSAlnfoLevel is the level of information required, and determines which item the data in DataBuffer 
refers to. 

Level 0x0001 returns data for the specific drive or device name referred to by DeviceName. The Ordinal 
field is ignored. 

Level 0x0002 returns data for the entry in the list of character or pseudo-character devices selected by 
Ordinal. The DeviceName field is ignored. 

Level 0x0003 returns data for the entry in the list of drives selected by Ordinal. The DeviceName field is 
ignored. 

DataBuffer is the return information buffer, it is in the following format: 


struct { 
unsigned short iType: 
unsigned short coName; 
unsigned char szName[{]; 
unsigned short cbFSOName; 
unsigned char szFSDNamef{]; 
unsigned short cbFSAData; 
unsigned char rgFSAData[]: 


}: 
iType typeof item 


Resident character device 
Pseudo-character device 
Local drive 

Remote drive attached to FSD 


& Gh — 
ioueu t 


cbName Length of item name, not counting null. 

szName_ item name, ASCIIZ string. 

cbFSOName Length of FSD name, not counting null. 
szFSOName Name of FSD item is attached to, ASCIIZ string. 
cbFSAData Length of FSD Attach data returned by FSD. 
rgFSAData FSD Attach data returned by FSD. 


szFSDName is the FSD name exported by the FSD, which is not necessarily the same as the FSD 
name in the boot sector. 

For local character devices (iType = 1), cbFSDName = 0 and szFSDName will contain only a 
terminating NULL byte, and cbFSAData = 0. 

For local drives (iType = 3), szFSDName will contain the name of the FSD attached to the drive at the 
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time of the call. This information changes dynamically. If the drive is attached to the operating system 
kernel's resident file system, szFSDName will contain "FAT" or "UNKNOWN". Since the resident file 
system gets attached to any disk that other FSDs refuse to MOUNT, it is possible to have a disk that does 
not contain a recognizable file system, but yet gets attached to- the resident file system. In this case, it is 
possible to detect the difference, and this information helps programs in not destroying data on a disk that 
was not properly recognized. 

DataBufferLen is the byte length of the return buffer. Upon return, it is the length of the data returned in 
DataBuffer by the FSD. 


Returns: IF ERROR (AX not = 0) 


AX = Error Code: 


ERROR_INVALID_ DRIVE - the drive specified is invalid 

ERROR _ BUFFER OVERFLOW - the specified buffer is too short for the 
returned data. 

ERROR_NO_MORE_ITEMS - the Ordinal specified refers to an item not in 
the fist. 

ERROR_INVALID LEVEL - invalid info level 


information about all block devices and all character and pseudo-character devices is returned by 
DosQFsAttach. The information returned by this call is highly volatile. 

Preferably, calling programs should be aware that the returned information may have already changed 
by the time it's returned to them. The information returned for disks that are attached to the kernel's 
resident file system can be used to determine if the kernel definitely recognized the disk as one with its file 
system on it, or if the kernel just attached its file system to it because no other FSDs mounted the disk. 

The set of error codes for errors general to all FSDs is OxEE00 - OxEEFF. The following errors have 
been defined although others may be added as needed: 

ERROR_VOLUME_NOT_ MOUNTED = OxEE00 - The FSD did not recognize the volume. 

The set of error codes which are defined by each FSD are OxEFOO - OxFEFF. 

Disk media and file system layout are described by the following structures. The data which are 
provided to the file system may depend on the level of file system support provided by the device driver 
attached to the block device. These structures are relevant only for local file systems. 


/* file system independent - volume params */ 
struct vpfsi { 


unsigned long vpi vid: /* 32 bit volume ID */ 
unsigned long vpi hDEV; /* handle to device driver * / 
unsigned short vpi_bsize; /* sector size in bytes */ 
unsigned long vpi_totsec; /* total number of sectors */ 
unsigned short vpi_trksec: /* sectors / track */ 
unsigned short vpi_nhead; /* number of heads */ 
char vpi_ text{12]: /* asciiz volume name */ 
be /* vptsi */ 


/* file systern dependent - volume params */ 
struct vpfsd { 
char vpd work(36]; /* work area */ 
I: /* vpfsd */ 
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As mentioned above, the FS_ MOUNT function is called to mount and unmount volumes and its 
purpose is to examine volumes to determine whether an FSD it recognizes the file system format. The 
sequence for calling FS-Mount is as follows: 


int far pascal FS_ MOUNT (flag, pvpfsi, pypfsd, hVPB, pBoot) 
unsigned short ~ flag; 

struct vpfsi far * pvpfsi: 

struct vpfsd far * pvpfsd: 

unsigned short hVPB; 

char far * pBoot; 


Where: 
flag indicates operation requested. 
flag = 0 indicates that the FSD is requested to mount or accept a volume. 
flag = 1 indicates that the FSD is being advised that the specified volume has been removed. 
= 2 indicates that the FSD is requested to release all internal storage assigned to that volume as it has 
been removed from its drive and the last kernel-managed reference to that volume has been removed. 
flag = 3 indicates that the FSD is requested to accept the volume regardless of recognition in preparation 
for formatting for use with the FSD. 

All other values are reserved. The value passed to the FSD will be valid. 

pvpfsi - A pointer to file-system-independent portion of VPB. If the media contains an operating system- 
recognizable boot sector, then the vpi__vid field contains the 32-bit identifier for that volume. If the media 
does not contain such a boot sector, the FSD generates a unique label for the media and places it into the 
vpi__vid field. 

pvpfsd - pointer to file-system-dependent portion of VPB. The FSD may store information as necessary 
into this area. 

hVPB - handie to volume. 

pBoot - pointer to sector 0 read from the media. This pointer is ONLY valid when flag = = 0. The buffer 
the pointer refers to MUST NOT BE MODIFIED. The pointer is always valid and does not need to be 
verified when flag = = 0; if a read error occurred, the buffer will contain zeroes. 

The FSD examines the volume presented and determines whether it recognizes the file system. If so, it 
returns zero after having filled in appropriate parts of vpfsi and vpfsd. The vpi__vid and vpi_ text field are 
filled in by the FSD. {ff the FSD has an operating system format boot sector, it converts the jabel from the 
media into asciiz form. The vpi_hDev field is filled in by the operating system. If the volume is 
unrecognized, the driver returns non-zero. 

The vpi__text and vpi-vid are updated by the FSD each time these values change. 

The contents of the vpfsd are as follows: 

FLAG = 

The FSD issues an FSD_FINDDUPHVPB to determine whether a duplicate VPB exists. If one exists 
the VPB fs dependent area of the new VPB is invalid and the new VPB is unmounted after the FSD returns 
from the FS__MOUNT call. The FSD updates the fs dependent area of the old duplicate VPB. 

If no duplicate VPB exists the FSD initializes the fs dependent area. 

FLAG = 

VPB fs dependent part is same as when FSD last modified it. 

FLAG = 

VPB fs dependent part is same as when FSD last modified it. 

After media the recognition process, the volume parameters may be examined using the 
FSH_GETVOLPARM call. The volume parameters should not be changed after the media recognition 
process. 

During a mount request, the FSD may examine other sectors on the media by using FSH__DOVOLIO to 
perform the I/O. If an uncertain-media return is detected, the FSD is "cleans up" and returns 
ERROR_UNCERTAIN_ MEDIA to allow the volume mount logic to restart on the newly-inserted media. The 
FSD provides the buffer to use for additional I/O. 

The operating system kernel manages the VPB via the refcount counter mentioned above. All volume- 
specific objects are labelled with the appropriate volume handle and represent references to the VPB. When 
all kernel references to a volume disappear, FS_ MOUNT is called with flag = 2, indicating a dismount 
request. 
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When the kernel detects that a volume has been removed from its drive, but there are still outstanding 
references to the volume, FS_ MOUNT is called with flag = 1 to allow the FSD to store clean (or other 
regenerable) data for the volume. Data which is dirty and cannot be regenerated is retained so that the data 
may be written to the volume when it is remounted in the drive. For the purposes of the present invention, 
clean data ts data which is unchanged and dirty data is data which has been modified. 

When a volume is to be formatted for use with an FSD, the operating system kernel calls the FSD's 
FS__MOUNT entry with flag = 3 to allow the FSD to prepare for a format operation. The FSD accepts the 
volume even if it is not a volume of the type that FSD recognizes, since format changes the file system on 
the volume. The operation may be failed if formatting cannot be completed. (For example, an FSD which 
supports only CD-ROM.) 

Since most computer system hardware does not allow for kernel-mediated removal of media, it is 
certain that the unmount request is issued when a volume is not present in any drive. 

FSH_DOVOLIO performs I/O to a specified volume. FSH _DOVOLIO formats a device driver request 
packet for the requested I/O, locks the data transfer region, calls the device driver, and reports any errors to 
the hard error daemon before returning to the FSD. Any retries indicated by the hard error daemon or 
actions indicated by DOSERROR are done within the call to FSH_DOVOLIO. 

The following describes the calling format for FSH__DOVOLIO. 


int far pascal FSH_DOVOLIO (operation, hVPB, pData, pcSec, iSec) 
unsigned short operation; 

‘ unsigned short hVPB; 
char far * pData; 


unsigned short far * pcSec; 
unsigned long iSec; 


Where: 

The operation bit mask indicates read/read-bypass/write/write-bypass/verify-after-write/write-through and 

no-cache operation to be performed. 

Bit 0x0001 off indicates read. 

Bit 0x0001 on indicates write. 

Bit 0x0002 off indicates no bypass. 

Bit O0x0002 on indicates cache bypass. 

Bit 0x0004 off indicates no verify-after-write operation. 

Bit 0x0004 on indicates verify-after-write. 

Bit 0x0008 off indicates errors signalled to the hard error daemon. 
Bit 0x0008 on indicates hard errors will be returned directly. 
Bit 0x0010 off indicates 1/0 is not "write-through”. 

Bit 0x0010 on indicates I/O is “write-through”. 

Bit 0x0020 off indicates data for this I/O should be cached. 

Bit Ox0020 on indicates data for this 1/O should not be cached. 
All other bits are reserved are zero. 

The difference between the “cache bypass" and the “no cache" bits is in the type of request packet 
that the device driver will is passed. With “cache bypass", it will get a packet with command code 24, 25, 
or 26. With "no cache", the system gets the extended packets for command codes 4, 8, or 9. 
hVPB volume handle for source of I/O 
pData long address of user transfer area 
pcSec pointer to number of sectors to be transferred. On return this is the number of sectors successfully 
transferred. 
iSec sector number of first sector of transfer 
Returns Error code if operation failed, O otherwise. 

ERROR_PROTECTION_ VIOLATION - the supplied address/length is not valid. 

ERROR_UNCERTAIN MEDIA - the device driver can no longer reliably tell if the media has been 
changed. This occurs only within the context of an FS_ MOUNT call. 

ERROR_TRANSFER_TOO_LONG - transfer is too long for device 
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FSH DOVOLIO may be used at all times within an FSD. When cailed within the scope of a 
FS MOUNT call, it applies to the volume in the drive without regard to which volume it may be. However, 
since volume recognition is not complete until the FSD returns to the FS_ MOUNT call, the FSD must take 
special precautions when an ERROR_UNCERTAIN_ MEDIA is returned. This indicates that the media has 
gone uncertain trying to identify the media in a drive. This may indicate that the volume that the FSD was 
trying to recognize was removed. In this case, an FSD releases any resources attached to the hVPB passed 
in the FS_MOUNT call and returns ERROR_UNCERTAIN MEDIA to the FS_MOUNT call. This will 
direct the volume tracking logic to restart the mount process. 

FSDs call FSH_ DOVOLIO2 to control device driver operation independently from I/O operations. This 
routine supports volume management for IOCTL operations. Any errors are reported to the hard error 
daemon before returning to the FSD. Any retries indicated by the hard error daemon or actions indicated by 
DOSERROR are done within the call to FSH_ DOVOLIO2. 


int far pascal FSH DOVOLIO2 (hDev, sfn, cat, func, pParm, cbParm, pData, cbData) 
unsigned long hDBev: 

unsigned short sfn; 

unsigned short cat; 

unsigned short func; 

charfar* pParm; 

unsigned short cbParm; 

char far* pData: 

unsigned short cbData; 


Where: 

hDev device handle obtained from VPB 

sfn system file number from open instance that caused the FSH DEVIOCTL call. This field should be 
passed unchanged from the sfi selfsfn field. If no open instance corresponds to this call, this field is set to 
OxFFFF. 

cat category of IOCTL to perform 

func function within category of IOCTL 

pParm long address to parameter area 

cbParm length of parameter area 

pData long address to data area 

cbData length of data area 

Returns Error code if error detected, 0 otherwise. 

The ERROR_INVALID FUNCTION is invoked when a function supplied is incompatible with the 
system of the present mention. It allocates a new VPB whenever the media becomes uncertain (the device 
driver recognizes that it can no longer be certain that the media is unchanged). This VPB cannot be 
collapsed with a previously allocated VPB (due to a reinsertion of media) until the FS__ MOUNT call returns. 
However, the previous VPB may have some cached data that must be updated from the media (the media 
may have been written while it was removed). FSH_FINDDUPHVPB allows the FSD to find this previous 
occurrence of the volume in order to update the cached information for the old VPB. The newly created 
VPB is unmounted if there is another, older VPB for that volume. 

The calling format for FSH__FINDDUPHVPB is as follows. 


int far pascal FSH FINDDUPHVPB (hVPB, phVPB) 
unsigned short hVPB: 
unsigned short far * phVPB;: 


Where: 
hVPB handle to the volume to be found 
phVPB pointer to where handie of matching volume will be stored. 
Returns Error code if no matching VPB found. 0 otherwise. 

ERROR_NO_!TEMS - there is no matching hVPB. 

FSH_GETVOLPARM allows an FSD to retrieve file-system-independent and -dependent data from a 
VPB. Since the FS router passes in a VPB handle, individual FSDs map the handle into pointers to the 
relevant portions. The calling sequence for FSH_ GETVOLPARNM is as follows: 
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void far pascal FSH _GETVOLPARM (hVPB, ppVPBtsi, pp VPBfsd) 
unsigned short hVPEB; 

Struct vpfsi-far * far * ppVPBfsi:; 

Struct vpfsd far * far * ppVPBfsd; 


Where: 

hVPB volume handle of interest 

ppVPBfisi location of where pointer to file-system- independent data is stored 
ppVPBfsd location of where pointer to file-system- dependent data is stored 
Returns: Nothing 

Because FSD-Volume mapping is dynamic, and FSD-DD connections are achieved through the 
operating system kernel in an FSD and DD independent way, any FSD may access any volume, including 
volumes whose DDs where loaded from that FSD. Since a volume maps to a particular piece of removeable 
media or to any partition on any partitionable media, it is contemplated that multiple FSDs may have access 
to a particular hard disk or other media. 

Volume file operations are divided into two categories: Named-based operations and handle-based 
operations. Name-based operations are typically initiated by a user wherein a user instructs the system 100 
to perform a named operation on a file. Handle-based operations are typically initiated during the 
background operation of the system. Handle-based operations are usually preceded by a name-based 
operation. 

Referring now to Figure 8, the routine 800 is invoked when the system 100 performs named-based 
operations. A named operation is an operation which is directed by a character name, i.e. the operation is 
specified with the name of a file or directory. "Open file 'xxx'" is one example of a name-based operation. 
Process 802 is invoked to parse the name and return three variables: PathNameType; TCBThishVPB and 
TCBThisFSC. Process 802 is discussed in detail in conjunction with Figure 9. (Note: h denotes a handle 
and TCB refers to a thread control block wherein TCHThishVPB is handle to the VPB currently of interest 
and TCBThisFCH is the pointer to the file system of interest). Item 804 then routes control to the 
appropriate function based on the variables PathType, TchThishVPB and TCBThisFCH returned by process 
802. Control is passed item 806 if the path began with "\\" indicating a Universal Naming Convention (UNC) 
global network name in which the UNC FSD is invoked. If a local device is indicated, contro! passes to item 
808 to process the request within the kernel. If a pseudodevice or remote file is indicated, control passes to 
item 810 to route the request to the remote FSD to which the pseudodevice or remote file is attached. If a 
named pipe is detected, control passes to item 812 to call the local named pipe code within the kernel. If a 
local file is indicated, control passes to item 814 which is the FSD worker in the FSD which performs reads 
and writes to the volume by calling FSHDOVOLIO in item 816. FSHDOVOLIO is discussed further in 
conjunction with Figure 11. 

Referring now to Figure 9, the parsing process 802 is described. When invoked, item 902 transforms 
the name of interest to a cannoical form based on current drive, current directory and the name itself. The 
variables TCBTHISFSC and TCHThisVPB and pathnametype are then determined as follows. Decision 904 
determines whether the user name begins with "\\" to determine whether a UNC name ts indicated. If so. 
control passes to item 905, wherein the values of the variables PathType, TchThishVPB and TCBThisFCH 
are initialized to route the user name to the appropriate location. If not, decision 906 determines whether the 
name of interest is a name in the device name list maintained by the kernel. If so, decision 908 determines 
whether it is a pseudo-character device. If so, item 910 sets the variables as indicated. If not. control passes 
to item 912 which sets the variables as indicated. 

Decision 914 determines whether the name represents a named pipe by looking for "ipipe\" at the 
beginning of the name. If so, item 916 set the variables as indicated. If not, decision 918 determines 
whether the name indicates a pathname on a local or remote drive. If a remote drive is indicated, control 
passes to item 920 which sets the variables PathType, TchThishVPB and TCBThisFCH as indicated. 
Otherwise, control passes to item 922 which calls what volume to read the appropriate data from the 
volume. When WhatVolume returns, control passes to item 924 which sets the variables PathType, 
TchThishVPB and TCBThisFCH as indicated. 

Referring now to Figure 10, the process 1000 is invoked for handle-based operations. When invoked, 
item 1002 retrieves an SFT entry. The SFT entry and the handle are both set up by DosOpen. TCBThisFSC 
is then set as indicated. Item 1004 then cails the relevant FSD worker for the file system that FSC points to. 
The hVPB is passed along from the SFT entry. Item 1006 then calls item 1016 to perform any I/O 
requested by the caller by calling item 1016 as required. 
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Referring now to Figure 11, FSH Do Vol IO is shown. When invoked in item 1102 the hVPB is used to 
determine what volume is in the drive as well as the volume of interest. Decision 1104 then determines 
whether the volume in the drive is the volume of interest. If so, 1106 is invoked to call the device driver and 
to perform I/O with the parameters specified. Decision 1108 then determines whether the media went 
uncertain during the operation. If not, the process returns in item 1114. If decision 1108 determines the 
media is not uncertain, control passes to item 1112 where WhatVolume is invoked to make the media 
certain. Control then returns to decision 1104. If the volume in the drive does not match the volume of 
interest, item 1110 is invoked to call HardError to instruct the user to place the correct volume in the drive. 
Control then passes to item 1112 described above. 

Appendices Il - VI are included herewith as an example of an installable file system source where: 
Appendix Il is a listing of exported interfaces a file system is expected to support in accordance with the 
teachings of the present invention. 

Appendix Ill is a listing of interfaces exported by a kernel which a file system may use. 

Appendix IV is the source code of an example of an installable file system constructed in accordance 
with the present invention. 

Appendix V is a listing of a definitions file used by the OS/2 linker to build the FSD of Appendix IV. 
Appendix VI is a header file that defines structures and parameters used by the IFS of Appendix IV. 

In summary, an improved method and system for dynamic volume tracking in an installable file system 
has been described. In accordance with the teachings of the present invention, a computer system is 
provided with a plurality of file system drivers which are organized in a linked list. The system is further 
provided with a default file system driver. Whenever a new volume is presented to the system or whenever 
media becomes uncertain, the system automatically and dynamically invokes the file system drivers until a 
file system driver accepts the volume. If no file system driver accepts the volume, the default file system is 
mounted. Accordingly, other uses and modifications will be apparent to persons of ordinary skill in the art. 
All such uses and modifications are intended to fall within the spirit and scope of the appended claims. 


Claims 


1. A method for mounting a file system for use in communicating with a data storage device and a 
computer system comprising the steps of: 
a) including a plurality of file system modules in a computer operating system including a default file 
system wherein said file systems are organized in a linked sequence; 
b) coupling a data storage device to said computer system; 
c) detecting a change in media in said data storage device or the first time said computer system 
accesses said data storage device: 
d) loading a file system identified in said list of file systems; 
e) reading a volume identifier from said media wherein the location of said volume identifier is specified 
by said loaded file system; 
f) comparing the read volume identifier from said media with the identifier associated with said file 
system; 
g) mounting said file system if said identifiers match; 
h) loading the next file system identified in said list of file systems if said identifiers do not match; 
i) returning to step (e) until each file system in said list of file systems has been tested or until a match is 
found; and 
j) mounting a default file system if no match is found. 
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1.0 GENERAL OBJECTIVES 


1.0.1 Summary of Functional Characteristics 


1.0.1.1 Improved User Interface 


The user ipterctsace is greatly improved to include the cepabllity to run and 
view multiple programs at the same time. for additional information see the 
Presentation Manager specification. 


1.0.1.2 Installable File System Mechanism 


The °‘¢::)lable File System will enable users to replace the present file 
SY SLE... AI based, with a file system of their choice. The user may choose 
the file system which meets their needs. This will provide the user with 
the capability of utilizing a greater disk capacity, additional file 
flexability, or the potentia! for increased performance. They can have 
multiple active file systems on a single PC, with the capability of multiple 
aud Gifferent slucage devices. And there is support for multiple logical 
volumes (partitions). 


3.0.1.3 Long Name Support 
Long Name support means that a program (like our uttiities or command line 
processors) must understand that: 
ASCIIZ string representing fully qualified fille speciticatilons (i.e. 
drive letter, path, and (ite name) may now be up to 260 bytes in length, 


and may get bigyer in a future release. 


Note: MAXPATHLEN defined in Duscalis.Hwe and DusQsysInfo can be used to 
determine the maximum path length. 


ASCIL2. string representing a file name component may be 255 bytes in 
length. 
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Any program which assumes a file name component of 13 bytes must be 
changed. Long File Names will only be supported in protect mode. The 
FAT file system will continue to only support 8.3 names. While spaces 
are valid file name characters, our utilities will continue to not 
support them. 


Note: MAXCOMPLEN can be used to determine the maximum file name 
component length. The structures in Doscalis.Hwce will be changed to use 
MAXCOMPLEN instead of 13. 


The file system defines the component separator within a file name to be 
‘.’. However, there is no ilmit on the number of components which may be 
allowed within 2 file name. Any program which is counting on only 
finding one period within a tile name must be changed. 


The file system allows the component separator within a path name to be 
*/* or “XS. Our utlbities will cantinue to use the convention chat *\' 
is the path name component separator and ‘/‘ its the switch character. 


Components and other affected areas: 


C40 .EXE 


RESTORE 

The Spooler 

TREE 

xCOPY 

DOSCALLS. HWC 

Syatem Initialization 
VIO and KBD subsystems and KEYH utility 
NLS 

Session Manager 

Shel} 

Swapper 

Message Retriever 
DosSearchPath 


1.0.1.3.] Meta Character Semantics: 


Use DosFindFirst/DosFindNext to determine all source files which match 
the wildcard name. (This is probably not a change for any program.) 


The tlle system will provide a new AP1 to transform a soucce file name 
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into a destination file name for a given editing string. Al] utilities 
which must perform name conversion (like copy or rename) should change 
to use this new AP1. The API is called DosEditName. 


Any program which must convert a file specification to its fully 
qualitied form (i.e. derive letter, path, tile mame) should use 
DosQPathInfo Level 5. 


Any program which currently defaults the source file name to *.* like 
DIR and ERASE must change the default to “#*. 


CMD.EXE and COMMAND.COM must prompt the user for vecification when he 
specified “DEL *" toc any file system or “DEL *.*" for the FAT file 
system. 


DosEditName will] have the following interface: 


extern unsigned far pascal DosEditName { 
unsigned EditLevel, 
char far *SourceString, 
char far *£ditString, 
char far *TargetBuf, 
unsigned TargetBufLen 
; 


The meat igs of the flelds are defined below: 


EditLevel Which semantics to use. 1 is currently the only defined level. 

SourceString A file name component with a maximum length equal to 
MAXCOMPLEN that contains no meta characters, no path characters, 
and no drive specification. 


EditString A file name component with a maximum length equal to MAXCOMPLEN 
that can contain meta characters, but no path characters and no 
Grive specification. 


TargetBuf Where the resultant file name is stored 
TargetBufLen The size of TargetBuf. This is limited to MAXCOMPLEN. 
Components and other affected areas: 


CMD .EXE 
ATTRIB 
BACKUP 
CHKDSK 
COMP 
PRINT 
REPLACE 
RESTORE 
XCOPY 
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RECOVER 


1.0.1.3.2 Device Names: 
1.0.1.3.2.1 3xBox: 


No change from 08/2 1.1 and PC~DOS except that device names with bogus paths 
will now be accepted. 


1.0.1.3.2.2 Protect Mode: 

Paths and extensions are SIGNIFICANT on device names in protect mode as are 
trailing dots. This means that "C:\DEVICE" is different from “DEVICE.” which 
is different from “DEVICE”. This also means that ‘NUL.LST’ will create a 
file called ‘NUL.LST’. 

The following set of device names, as an exception, are said to exist itn ail 
directories: CON, KBD$, MOUSE$, COM1 thru COM9, LPTl thro LPT9, PRN, 
SCREENS, NUL, POINTERS, CLOCKS. 

All other devices, whether installed or pseudo, exist only in the directory 
\DEV\, and thus may only be reached with a path of the form \DEV\DEVNAME. 
What this also means is that if you attempt to fully qualify a device name, 
using DosQPathInfo level 5, it will get a \DEV\ prepended to it. 

1.0.1.3.3 General Utility Changes: 

1.0.1.3.3.1 Dir Command: 

8 FAT filesystem and /N, /W, and /F not specified 


Display exactly as today: edited file name, file size data, last update 
date, last update time. 


a Non FAT filesystem or /N specified 
- {WW switch not specifed 


Last update date, last update time, file size data, file size 


extended attributes, unedited file name 

- /W awitch is specified 
The list of found files is pre-scanned to find the longest file 
name. The width of che screen is divided by the longast file name 
to determine the number of files that will be displayed per line. 
Unedited filenames are displayed in columnar format. 


. /F switch 


Displays the fully qualified file mame of each matching file. Wo 
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g or tratling information is displayed. 


2 Searching For Executables: 


on describes the chanyes for suppurting Searching For Executables 
in the Long File Name environment. . 


The old method was as follows: 


lh. Ifa 
remain 
2. In the 


The new me 


*.' existed in the file name component, strip of the ’.? 
ing characters. 


and any 


current directory and for each path in PATH attempt to find the 
file with an added extension of *.COM’, ‘. EXE’, °.CMD’. 


thod ts as follows: 


1. If the extension is not empty, i.e. there is at least one ‘.' 
ame and what follows the last ’.* ts not NULL look for the file as 


file n 
specif 


2. If the 


3. Anythi 


ied, 
extension is ’ .CMD’ or °.BAT*’ execute it a8 a batch file. 


ng else is treated as an executabje file 


in the 


4. If the extension was empty or file not found, then in order append, 


* .COM’ 


5. If not 
in pat 


. '-EXE’, *.CMD’ and look for file. 


in current directory, repeat steps 1 thru 4 for all directories 


h. 


The following examples will illustrate the search order. 


FOO 
FOO. 
FOO.EX1 
FOO .BAT 


FOO. EXE 
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FOO.COM, FOO.EXE, FOO.CcMD 

FOO. .COM, FOO..EXE, FOO. .CMD 

FOO.EX1, FOO.EX1.COM, FOO.EX1.EXE, FOO.EX1.CMD 
FOO.BAT, FOO.BAT.COM, FOO.BAT.EXE, FOO.BAT.CMD 


FOO.EXE, FOO.EXE.COM, FOO.EXE.EXE, FOO.EXE.CMD 


3 1FS versions of CHKDSK, FORMAT, RECOVER, SYS: 


* Only have to run in protect mode 


® Wild 
export 


be contained in a file called Uxxxuxxx.DLL, where Xxxxxxx 
ed name of the FSD. 
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xx4xXxxx Should be (up to) the first 7 characters of the exported FSD 
name, since we do not limit the name to 7 (or less) characters. 


* The entry points within Uxxxxxxx.DLL will be the name of the utility 
whose function they provide. 

1.0.1.3.3.4 DISKCOMP and DISKCOPY: 

Will continue to handle diskettes written by any file system. Document 

strange case under which DISKCOPY corrupts data because it thinks it is the 

volume serial number and DISKCOMP would not notice a mismatch when working 

with IFS formatted diskettes. 

1.0.1.3.3.5 FORMAT: 


Will use the following algorithm to determine how to format the volume: 


e If the user specified /FS:xxxxxxx then format the volume for the 
specified file system. 


. Jf the volume is already formatted, reformat it for the same file 
system. 


. If in protect mode and there exists an environment variable for FORMAT~y 
where y is /FS:xxxxxxx, format the volume for the specified file system. 


" Format the volume for the FAT file systen. 

* 1f FORMAT was started in the real mode environment, and it would 
otherwise format for a file system other than FAT, reject the request. 

1.0.1.3.3.6 UTILAPI.LIB: 


Provides mode-independent support without adding into FAP] (API.LIB) 
interfaces which are not supported by PC/DOS. 


* DosDevioct]2 (performs DosPevioctl function) 


" DosQFsAttach {returns FSD name) 


1.0.1.3.3.7 System Installation: 


If the user specifies to format the OS/2 partition for any file system othe: 
than FAT, add the statement "SET FORMAT#/FS:xxxxxxx"® to che CONFIG.SYS file 
(xxxxux is the name of the selected file system). 
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1.0.1.3.4 Long Names Fot Non-file System Objectives: 

File paths now allow up to 260 bytes (including trailing null byte). This 
same limit should apply to non-file system objects. This includes queue 
names, system semaphore names, shared memory names, and named pipe names. 


1.0.1.3.4.1 Queue Names: 


Queue names are currently limited to 128 bytes (by a loca! symbolic constant 
and several references to 128). 


Queue names should be limited to the same length as other paths (260 bytes) . 


1.0.1.3.4.2 System Semaphore Names: 

System Semaphore names are currently limited by the size of RMP buffers (260 
bytes), but it stores two extra bytes, so the name portion is limited to 258 
bytes (with trailing null). 

System Semaphore names up to 260 bytes should be allowed {including the 
trailing null). 


1.0.1.3.4.3 Shared Memory Names: 


Shared Memory names are currently limited to 259 bytes (including trailing 
null}, due to an off by one error {which did not appear prior to 1.2). 


Shared Memory names will be fixed to allow up to 260 bytes. 


1.0.1.3.4.4 Named Pipe names: 
Named Pipe names were limited to 128 bytes in 1.1. 


Named Pipe names will be updated to allow up to 260 bytes (aiready done). 


1.0.1.3.4.5 Long Paths in the 3xBox: 


The J3xBox should support a maximum of 260 bytes for paths. (Note that 
current directories are Limited to 64 bytes in the 3xHox.} (Note also that 
filenames {components} which cannot be expressed as 8.3 are invisible in the 
3xBox.} 
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1.0.1.3.4.6 Long Paths and Long Names in the Loader: 


The loader will support long paths up to 260 byates and long names up to 255 
bytes (without trailing null). 


Affected areas are DLL loading and DosExecPgqm. For DLLs, the module name 
will continue to be the filename without the .DLL suffix. 
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#4 2.0 FUNCTIONAL CHARACTERISTICS 


# 2.1 PROGRAMMING INTERFACE 
# 2.1.0.1 File System Enhancements 
# 2.1.0.1.1 GET/SET EXTENDED ATTR. (INT 21H, 5702H and 5703H): 
# Purpose The Real Mode Box File Date/Time Interrupt 21H will support 
# setting extended attributes as well as other information. To 
# query Extended Attributes, a subset or all of the’ EA information 
$ for «a file can be retrieved. To set Extended Attributes a list of 
i one or more type codes with values is supplied. Additionally the 
i FAPI interface supports info levels to get or set information via 
# DOSQFILEINFO, DOSQPathInfo, DOSSetFileInfo, and DOSSetPathInfo. 
# This will allow OS/2 utilities to have the function of these calls 
# in real mode. 
# The INT21H, AX=5702H and 5703H API will be unpublished in both 
# OS/2 and TUGBOAT. 
# Format Calling Sequence: 
# Get/Set Extended Attributes 
# For GET subset of Extended Attributes (AX=5703H, DX=3): 
i MOV AX, 5703H 7 Get information 
# MOV BX, HANDLE ¢ File handle 
# MOV Dx, 3 3; Get Extended Attributes subset 
# LDS SI, FileName ; Filename (use if BX=OFFFFH) 
# LES DI, EABuf ; Extended Attribute EAOP 
# INT 21H 
# Jc ERROR 
# For GET Extended Attributes, all (Ax=5704H, DxX=4): 

2.0 Functional Characteristics 9 
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MOV AX,5703H 
MOV BX, HANDLE 
MOV DX, 4 

LDS SI,FileName 
LES DI, EABuf 
INT 21H 

JC ERROR 

For SET (5704): 

MOV AX, 5704H 
MOV BX, HANDLE 
MOV DX, 2 

LDS SI, FileName 
LES DI, LIST 

INT 21H 

Jc ERROR 

FAPI support for utilities 
For GET Information (5703H) 
MOV AX, 5703H 
MOV BX, HANDLE 
MOV CX, BUFLen 
MOV DX, InfoLevel 
LDS SI,FileName 
LES DI, BUFFER 
INT 21H 

JC ERROR 

For SET Information (5704h) 
MOV AX,5704H 
MOV BX, HANDLE 
MOV CX, BUF Len 
MOV DX, InfoLevel 
LDS SI,FileName 
LES DI, BUFFER 
INT 21H 

Jc ERROR 


Where: HANDLE is the handle returned by a previous file open. 


FileName is the 
subdirectory. 


EABuf is an EAOP structure with the following format. 
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Get Extended Attributes all 
Filename {use if BX=OFFFFH) 


Extended attr. EAOP structure 


SET EXTENDED ATTRIBUTES 


Set Extended Attributes 
Filename (use if BX=0FFFFH) 
Extehded attr. list 


Get information 

File handle 

Length of buffer 
Information level 

Filename (use if BX=OFFFFH) 
Information buffer 


Get information 

File handle 

Length of buffer 
Information level 

Filename (use if BX=OFFEFFH) 
Information buffer 


ASCIIZ full path name of the file or 
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EAOP structure 

dword pointer to a GEAList 
dword pointer to a FEAList 
Error offset 


EAOP struc 
fpGEAList dd 
fpFEAList dd 
offError dw 
EAOP ends 


ww oO 
se 


ww 


we Ge Be 


where GEAList is a structure with the following format: 


GEAList struc ;GEA list structure 
ListSize dw 2? glength of list 
GEA <?,?,?,..> ;packed set of GEAs 
GEAList ends 


where GEA is a structure with the following format: 


GEA Struc 7;GEA structure 
NameSize db ? slength of name 
Name db ".....",0 sasciiz name 
GEA ends 


where FEAList is a structure with the following format: 


FEAList struc ;FEA list structure 

ListSize dw ? slength of list 

FEA ae St Oe Se ;packed set of FEAs 
; Seas 

FEAList ends 


where FEA is a structure with the following format: 


FEA struc sFEA structure 
reserved db 0 zreserved must be zero 
NameSize db 2 slength of name 
ValueSize db ? slength of value 

Name db eee ere» gasciiz name 

Value db ow Pa :free-format value 

FEA ends 


Note: The length of the name does not include the 
trailing null. Names are not limited to 8 characters, 
but may be up to 255 characters long. 

BUFLen is the size of the data buffer. 


BUFFER is the data buffer used to pass information. 
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InfoLevel is the level of information required. 
Returns: Successful Completion if carry is not set. 


Unsuccessful Completion if carry is set. AX = any valid 
extended error. If the error was caused by attempting 
to set an invalid valid extended attribute then offError 
in the EAOP structure contains the offset of the 
offending attribute. 


On a get extended attributes call the results are the same as the 
protect mode API call DOSOFileInfo when BX<>OFFFFH or DOSQPathInfo 
when BX=OFFFFH. 


On a set extended attributes call the results are the same as the 
protect mode API call DOSSetFilelInfo when BX<>0OFFFFH or 
pOSSetPathInfo when BX=0OFFFFH. 


The FAPI support for utilities calls for get and set information 
have the same info levels and input/output buffer structures as 
the protect mode API call DOSQFileInfo/DOSSetFileInfo when 
BX<>OFFFFH or DOSQPathInfo/DOSSetPathInfo when BX=OFFFFH. 


Note: See DOSQOFileInfo, DOSQPathInfo, 
DOSSetPathInfo for more information. 


DOSSetFileinfo, 


ENUMERATE EXTENDED ATTRIBUTES {INT 21H, 6EH): 


A new Interrupt 21H will be created to allow the enumeration of | 


Extended Attributes. This new function is modelled after the OS/2 
DOSENUMATTRIBUTE function. It combines the functions currently 
available with DOSENUMATTRIBUTE and DOSFSCTL function 2. 


Calling Sequence: 


MOV AH, 6EH ; Ennumerate EAs 

MOV AL, 0 ; Reserved 

LDS SI, ParmPkt ; DS:SI = Pointer to buffer 

INT 21H 

JC ERROR 

Where: ParmPkt is a structure containing the parameters to pass 


to the call. The structure is defined as follows, and is 
derived from the argument frame for DOSENUMATTRIBUTE: 
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EnumEASt ruc struc 


é 
eeas Reserved dd 0 ; Reserved. Must be zero 
eeas Infolevel dd ? ; Level of information req 
eeas EnumCnt dd ? ; Count of EAs 
eeas EnumBufSize dd ? ; Size of return buffer 
eeas EnumBuf dd ? ; Pointer to return buffer 
eeas EntryNum dd ? ; Entry in EA from which t< 
eeas FileRef dd ? + Pointer to Handle or Path 
eeas RefType dw ? ; Type of reference in Fil 
EnumEASt ruc ends 
eeas Reserved is reserved and must be set to zero. 
eeas InfoLevel contains the level of information desired. Level 
0x00000001 information is returned in the following 
format: 
struct { 
unsigned char reserved; /* must be 0 
unsigned char cbName; /* length of name exclud 
unsigned short cbValue; /* length of value 
unsigned char szName{]; /* asciiz name 
}3 
The fields in the structure are on a one-to-one mapping 
for the fields in an FEA structure. 
The information for the next EA will be stored adjacent 
to the previous one. An application that wishes to 


continue on from one DosEnumAttribute call would have to 
set EntryNum to the previous value plus the returned 
value in EnumCnt . 


The size of buffer needed to hold an EA can be obtained 
from the ennumerated information. An EA would occupy: 


one byte (for fea Reserved) + 

one byte (for fea cbName) + 

two bytes (for fea_cbValue) + 

value of cbName (for the name of the EA) + 

one byte (for terminating NULL in fea_cbName) + 
value of cbhValue {for the value of the EA) 


eeas EnumCnt contains, on input, the number of EAs whose 
information has been’ requested. The system will change 
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this to the number actually returned. An EnumCnt of -1 
is treated specially in that it will return as _ many 
entries as will fitin the buffer specified. 

size of the buffer at 


eeas EnumBufSize is the 


+ eeas EnumBuf. 

+ eeas EnumBuf is a pointer to the buffer where the 
+start requested information is returned. 

Ref eeas EntryNum is the ordinal of the entry in the EA list 
+ from which to start copying information into EnumBuf. 
+ The EntryNum value of zero is reserved, and the first EA 
+ is indicated by an EntryNum of 1. 

+ eeas FileRef contains a pointer to a WORD handle 
+ obtained from Open/Create, or to an ASCIIZ name of a 
+ file or directory, as indicated by eeas RefType. 

+ eeas RefType indicates whether eeas FileRef points to a 
+ handle or an ASCII2Z name. RefType = O indicates a 
+ handle; RefType = 1 indicates that FileRef points to an 
+ */ ASCIIZ name of a file or directory. 


ng NULL */ 
+ 


++ ete t 


+e eee e eet + 


*/Unsuccessful Completion if carry is set. 
*/error. 


AX = any valid extended 


Remarks The size of EnumBuf indicated in EnumBufSize should be at least big 
enough to hold the information for one EA. This will depend on the length of 
the EA’s name. 


It is important to note that the use of EntryNum in no way guarantees the 
specific ordering of the EAs. It is only a tool to ennumerate the EAs, and 
should not be used to “back up to the nth EA", since the EAs are subject to 
change by other tasks. So, for example, the EA returned when EntryNum is 11 
may not necessarily be the EA returned when EntryNum is 11 for a subsequent 
call if another task had performed a SET operation on the EALlist. 


No explicit EA sharing is done for DosEnumAttribute. Implicit sharing 
exists if the caller passes in the handle of an open file, since sharing 
access to the associated file is required to modify its EAs. No sharing is 


done if the caller passes in the pathname. This means that if some other 
process is editing the EAs, and changes them between two calls to 
DosEnumAttribute, inconsistent results may be returned (i.e. see same same 


value twice, miss seeing values, etc.) To prevent the modification of EAs 
for the handle case, make sure that the file is open in deny-write mode. To 
prevent the modification of EAs for the pathname case, open the file in 
deny-write mode. 
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4 2.1.0.1.3 QUERY FILE SYSTEM FOR MAX EA SIZE (INT 21H, 6FH): 


+ 
4 


= 


+ te te He he + 


Ce ee ee ee ee 


Purpose 


Format 


+ Remarks 


+ 
¢ 
+ 


4 2.1.0.1.4 


Purpose 
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A new Interrupt 21H will be created to allow querying of a file 
system for the maximum sizes of Extended Attributes supported. 


Calling Sequence: 

MOV AH, 6FH ; Query file system about EA sizes 

MOV AL, 0 : Reserved 

LDS SI, EASizeBuf ; DS:SI = Pointer to buffer 

LES D1, PathName ; ES:D] & Pointer to path name 

INT 21H 

JC ERROR 

Where: EASjzeBuf is a structure that will hold the returned 
sizes from the file system. The structure is defined as 
follows: 


EASizeBufStruc  { 
' unsigned short easb MaxEASize /* Max. size of 
individual E 


unsigned long easb MaxEAListSize /* Max. Full EA 
supported */ 


PathName is an ASCIIZ string that contains a path that 
is to be used to identify the file system that is to be 
queried. The file system that will be queried will be 
the one that is currently mounted on the volume to which 
PathName refers. 


Unsuccessful Completion if carry is set. AX «= any valid 
extended error. 


The information returned can be used by an application to decide 


whether an EA operation will succeed on a given file system before] 


the operation is attempted. This will have the effect of improved 
performance on certain environments, e.g. across a network. 


EXTENDED OPEN/CREATE (INT 21H, 6CH}: 


A new Real Mode Box OPEN Interrupt 21H will be created to allow 
Extended Attributes to be passed. This new function is modelled 
after the OS/2 OPEN2 function. lt combines the functions 
currently available with OPEN, CREATE and CREATE New. When 
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# creating, any Extended Attribute is allowed. 


# Format Calling Sequence: 


a MOV 
+ MOV 
+ 

+ OR 
+ MOV 
i MOV 
i] MOV 
i 

8 MOV 
# LDS 
# LES 
a INT 
# Jc 
+ Where: 
an 

+supported */ 
list size 

i 

@ 

q 

+ Cc 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 


AH, 6CH 
AL, 0 


AL, 1 
BX, MODE 
CX, ATTR 


DX, FLAG 
SI, FILE NAME 
DI, EABuf 

21H 

ERROR 


MODE 


wee Be Be a6 ee Se 


Extended open2 
for non Extended Attribute (ES:DI NOT 


required) 


for Extended Attribute (ES:DI required) 
Open mode 

Create attribute (ignored if file 
already exists) 

Function control 

Name to open or create 

Ext attr EAOP structure 


FORMAT : OWFCOOOOISSSOAAA 


AAA=Access code 0=Read 


1-Write 
2=Read/Write 


SSS=Sharing mode O0=<Compatibility 


Cache/No-Cache 


l=Deny Read/Write 
2=Deny Write 
3=Deny Read 
4=Deny None 


The file is opened as follows: 


If C = 0; 1/0 to the file need not be done 
through the disk driver cache. 


If C = l: It is advisable for the disk driver 
to cache the data in 1/0 operations 
on this file. 


This bit is an ADVISORY bit, and is used to advise FSDs 
and device drivers on whether it is worth caching the 
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data or not. This bit, like the write-through bit, is al]# ATTR is defined as follows. Note that the LIST of 
per-handle bit. It is not inherited by child processes.|4 attributes will override ATTR’s settings. 

# 
$ Bit # Meaning 
I O=Pass handle to child, 1=No inherit a 15 reserved = 0 
# 14 to 9 reserved = 0 
F Q=INT 24H, 1=Return error # 8 reserved = Q 
On this open and any I/O to this handle # 7 reserved = 0 
# 6 reserved = 0 
W O=No commit, l=Auto-commit on write # 5 Archive 
# 4 Directory 
# 3 Volume 
: 2 System 
$ 1 Hidden 
? 0 ReadOnly 
# FLAG 
; i : Format =QOQ000000NNNNEEEE 
§ NNNN=Does not exist action 
$ O=Fail, 1l=<Create 
$ EEEE=Exists action 
8 O=Fail, 1=Open, 2=Replace/Open 
§ EABuf 
q EABuf EAOP <> 


# EAOP is a structure used to pass extended attribute 
¢ information. See Get/Set Extended Attributes for a ful] 
# description of the EAOP structure. 


é If the caller does not want to pass any extended 
¥ attributes then DI must be set to OFFFFh. 
# Returns: Successful Completion if carry is not set. 
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# Remarks 


#2.1.0.1.5 


§ Purpose 


# Format. 
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AX = Handle 

CX = Action taken code 
O1H = FILE OPENED 
O2H = FILE CREATED/OPENED 
03H = FILE REPLACED/OPENED 


Unsuccessful Completion if carry is set. AX = any valid 


extended error. 


Any re-creation of a file (le, Create of file that already exists) 
does not delete any Extended Attributes defined for that file. 


GET/SET MEDIA 1D (INT 21H, 69H): 


This function allows the utilities and real mode command shell to 
query the volume serial number and volume label in real mode. 


Since IFS volume labels can be up to 255 characters long (TUGBOAT 


media call structure only allows for 11 and truncates longer 
names} there will be a FAPI interface giving the function of 
DOSQFsInfo and DOSSetFsInfo. This will allow OS/2 utilities to 


gain access to the full volume label. 


The INT 21H, AH=69H API will be unpublished in both OS/2 and 
TUGBOAT. 
Calling Sequence: 

19 
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Get/Set Media ID 


MOV 
MOV 


MOV 
MOV 
LDS 
INT 
Jc 


AH, 69H : GET/SET Media ID 
AL, SUBFUNCTION 3 0 = Get Media ID 
¢ 1 = Set Media ID 
BL, DRIVE : Drive number 
BH, 0 3; Reserved 
DX, BUFFER : Buffer containing information 
21H 
ERROR 


FAPI support for utilities 


MOV 
MOV 


MOV 


AH, 69H ; GET/SET Media ID 
AL, SUBFUNCTION : O = Get FSInfo 
: 1 = Set FSInfo 
BL, DRIVE : Drive number 
BH, Infolevel : Information level 
CX, BUFLen ; Buffer size 
DX, BUFFER 3; Buffer containing information 
21H 
ERROR 


SUBFUNCTION is either 0 to query or i to set. 

DRIVE is the number of the drive to be queried or set. 
BUFLen is the size of the data buffer. 

BUFFER is the data buffer where 


For the Get/Set Media ID calls the 
following format. 


information is passed. 
buffer has the 


MEDIAINFO struc 3: Media ID structure 
level dw 0 : reserved 

serial dd ? : serial number 
volume ab 11 dup(’ *) : Volume label 
fstype db 8 dup(’ ‘) 3; File system type 


MEDIAINFO ends 


The FAPI support for utilities calls for get and set 
File system information have the same info levels and 
input/output buffer structures as the protect mode AP! 
calls DOSQFsInfo and DOSSetFsInfo. 
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Note: See DOSQFsInfo and DOSSetFsInfo for more 
information. 

Returns: Successful Completion if carry is not set, buffer 
contains the information or information was set from 
buffer. 

Unsuccessful Completion if carry is set. 


Remarks The Get Media ID cal] will return blanks for the file system type 
in all cases Likewise the Set Media ID call will not set the 
serial number or file system type. 

The INT 21H, not be 


TUGBOAT. 


AH=69H function will published in OS/2 or 


2.1.0.2 Miscellaneous Enhancements 


2.1.0.2.1 QUERY DOS VALUE (INT 21H, 3305H): 
Purpose This function allows a Real Mode Box application to query the boot 
device. 
This function is being introduced for OS/2 1.2 compatibility. 
Format Calling Sequence: 
MOV AX, 3305H ; QUERY DOS VALUE 
INT 21H 
Jc ERROR 
Where: No input parameters. 
Returns: Successful Completion if DL = boot drive where 1 = A, 2 
= B, etc. 
Unsuccessful Completion if AL = OFFh. 
Remarks This function is being introduced for OS/2 1.2 compatibility. 
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2.1.1 Interprocess Communication 


To provide the means for allowing processes to communicate with one another, 
OS/2 supports four general methods of interprocess communication (IPC): 
flags, pipes, semaphores, and shared memory. All methods except flags work 
between the threads of one process, as well as inter-process. 


The IPC functions provided allow: 
* communication via flags, 
* communication via messages, 


* coordinating execution among several processes, 
' 
- one process to directly control execution of other processes, 


2.1.1.1 Communication via flags 


Communication via flags is used to allow one process to set an_ external 
The target process must use DosSetSigHandler 
“Hawn anew Smee wees ee eee “ on page --- to inform OS/2 that it wishes 
to intercept any of 3. flags; then, another process may issue a 
DosFlagProcess indicating which of the flags to signal. The target process 


will receive control at the signal handler it has defined for that signal. 


2.1.1.2 Communication via messages 


There are two facilities provided for 
messages - pipes and queues. 


interprocess communication via 


2.1.1.2.1 Pipes: 


For communicating via pipes, the standard OS/2 read and write functions are 
used. Pipe support is provided only for applications in which the pipe 
participants are a closely related group of processes. The functions 
provided are in the DosMakePipe function. 


Pipes are a technique by which two related processes may communicate as if 
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they were doing file 1/0. In fact, a program which inherits a pipe handle 


can not distinguish if its I/O requests to that handle are to a file or 
pipe. 

The storage required, or available, for a pipe 1/0 request to be performed 
may be a consideration. Pipes are effectively fixed length in nature with 


that any pipe can hold being 64 kb at any one time. 
requests will block until some data is 


If a pipe 
removed from 


the maximum 
is full, further write 
the pipe. 

2.1.1.2.2 Queues: 


The following functions are provided for communicating via Queues: 


DosCloseQueve Close a Queue. 

DosCreateQueue Create a Queue. 

DosOpenQueve Open a Queue. 

DosPeekQueve Get an element from Queue, but do not remove it. 
DosPurgeQueve Purge al} entries from a Queue. 

DosQueryQueve Find how many elements are in Queue. 
DosReadQueue Get an element from a Queue and remove it. 


DosWriteQueue Adds an element to a Queue. 


2.1.1.2.3 Comparing Pipes and Queues: 
Pipes are a technique by which two processes may communicate as if they were 


doing file I/O. In fact, a program which lists a file may have its input or 
would without 


output specified as being a pipe and the program operate 

change. The pipe support would insure that all data read or written by the 
program went to a pipe rather than to a file or a printer. 

Programs which use queves must be designed and coded with the concepts and 
system calls defined by queuing in mind. These calls are not at all like 
the file 1/0 calls and the processing of the data is completely different 
from that used with pipes. 


Another characteristic of interest is the relative performance offered by 
pipes or queves. Queves are more efficient than pipes as only a pointer to 
the data is passed. 


The storage required, or available, for the IPC to be performed is often a 
consideration. Pipes are effectively fixed length in nature (not over 64 kb 
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in length) while queues may be of relatively unbounded length since queue 
messages need not be contained in one segment. 


in the pipe’s data 
placed into a single 


While a pipe may contain as many messages as will fit 
segment, the total number of messages which may be 
queue is about 4000. 


take into account all these factors balancing 
against the storage usage characteristics of 


The application designer must 
the performance requirements 
each sqlution. 


2.1.1.3 Coordinating execution among several threads 


For 
functions. 
the various 
execution. 


coordinating the execution of several threads, OS/2 provides several 

In a multitasking application environment, these functions allow 
processes to have a great deal of control over one another's 

The functions provided include: 

* Semaphores - RAM based and file system based, 


* Starting and stopping a thread’s execution, 


2.1.1.3.1 Semaphores: 
Two types of semaphores are provided in 0S/2: 


which are 
double-word 


RAM Semaphores defined by the requesting program allocating a 
of storage and using the address in the 
semaphore calls provided below. RAM semaphores are a 
minimal function mechanism with OS/2 performing no 
resource management services such as freeing when the owner 
terminates. 
which are defined by OS/2 in response toa _ create 
semaphore system call. Once created, they may be accessed 
by separate processes and OS/2 will provide full resource 
management including freeing and notification when the 
owner terminates. 


System Semaphores 


The functions provided for controlling access to a serially reuseable 


resource (via either RAM or System semaphores) are: 


DosSemClear Clear a semaphore. 
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DosSemRequest Obtain a semaphore. 


To allow a simple wait/post 
functions are provided: 


DosSemSet Set a semaphore. 
DosSemSetWait Set a semaphore and wait for it to be cleared. 
DosSemWait Wait for a semaphore to be cleared. 


DosMuxSemWait Wait for any one of many semaphores to be cleared. 


type of signalling between threads, several 


And, these are provided to have OS/2 allocate, provide access to, and delete 


system semaphores: 


DosSemC lose Close a system semaphore. 

DosSemCreate Create a system semaphore. 

DosSemOpen Open a system semaphore. 

2.1.1.3.2 Starting and Stopping a Thread’s Execution: 

For explicitly controlling when a thread may execute, the following 

functions are provided: 

DosResumeThread Restart a thread's execution. 

DosSuspendThread Suspend a thread’s execution. 

The details of each of these categories will now be explored: 

2.1.1.3.3 DosFlagProcess - Set a Process’s External Event Flag: 

Purpose DosFlagProcess allows one process to set an “external event" flag 
on another. The target process can detect the triggering of this 
flag via DosSetSigHandler. By default, the event flag is ignored. 

Format Calling Sequence: 

EXTRN DosFlagProcess:FAR 
PUSH WORD ProcessID ; Process ID to flag 
25 
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PUSH WORD Action ; Indicate to send to process or subtree 
PUSH WORD Flagnum ; Flag number 
PUSH WORD Fiagarg ; Flag argument 
CALL DosFlagProcess 
where ProcessID is the process ID of the process’ to which the 
flag is to be sent. 
Action indicates to flag only the specified process or 
all descendents of the process. 
” If value=0 is coded, ali descendents will be 
notified. : 
* If value=1 is coded, only the indicated process wil] 
be notified. : 
Flagnum is the number of the flag to set: 
0 - flag A 
1 - flag B 
2- flag C 
FlagArg is an argument to be passed to the indicated 
process(es). 
Returns: IF AX = 0 
NO error P 
ELSE 


AX = Error Code: 

* Invalid Action 

* Invalid Process ID 

* Process refuses flag 

* Signal already pending 


* Process is zombie 


Remarks. DosFlagProcess does not actually set a static flag which can be 
checked at a later time; it causes a "flag event” to occur for the 
specified process(es). By default, a flag event is ignored by a 
Process. A process may use DosSetSigHandler “------ ----- <--<-- 
waeee onnee "on page --~ to be alerted, via the signal mechanism, 
when such a flag event occurs. A process may also specify that 
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# the flag action is to be ignored and that an error code is to be 
i returned to the flagger. The “Process is zombie” error code 
t indicates that the flagged process has died but its’ parent has 
| not yet done a DOSCWAIT to get its’ return code. 

# 2.1.1.4 Pipes 

# Pipes are an IPC mechanism based on the file 1/0 concept. 
[# When comparing pipes with files: 

q* similarities 

| - data is communicated to pipes by the standard DosRead and DosWrite 
t system calls, 

# - pipes are closed by the standard DosClose system call. 

#* 1=differences 

# - pipes are created by DosMakePipe rather than one of the file create 
# requests, 

$ - pipes need not be OPENed before being accessed, only the DosMakePipe 
# is necessary, 

§ - pipes are implemented via an in storage buffer mechanism rather than 
# having their data maintained on disk, 

| - when writing to a file, the requesting thread will be blocked only 
# while doing file I/O. When writing to a pipe, the requesting thread 
# will block if the pipe reader allows the pipe to fill up. 

| - writes to a pipe will not be interspersed. 

4 A thread issuing a write to a pipe will be blocked until it can 
| write all of the data specified to the pipe. No other thread may 
$ write to that pipe until the write in progress completes. Any 
4 thread that attempts to write to the pipe is blocked. 

$ - reading data from a pipe removes that data from the pipe, subsequent 
4 reads will not find that data. 

# Pipes are inherited the same as files. A using process would typically 
i create a pipe, then start a child process (who would inherit the pipe 


# handles) and communicate to the child process with the pipe’s handles. 
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# 2.1.1.4.1 DosMakePipe - Create a Pipe: 


# Purpose DosMakePipe creates a Pipe. 





# Format Calling Sequence: 

$ EXTRN DosMakePipe:FAR 

t PUSH@ WORD ReadHandle ; Address to place the read handle 

§ PUSH@ WORD WriteHandle ; Address to place the write handle 

§ PUSH WORD PipeSize : Size to reserve for the pipe 

# CALL DosMakePipe 

# where ReadHandle is the address of a word where the read 
i handle for the pipe is to be placed. 

i WriteHandle is the address of a word where the write 
3 handle for the pipe is to be placed. 


# PipeSize is the size, in bytes, of storage to reserve 
e for this pipe. 

# Returns: IF AX = 0 

# NO error 

3 ELSE 

f AX = Error Code: 

3 cs Not enough memory, pipe can not be created 


# Remarks Pipes are provided for use within a closely related group of 
# processes. There are no control or permission mechanisms or 
‘ checks performed on operations to pipes. 

§ Whenever there is not enough space in a pipe for the data being 
# written, the requesting thread will be blocked until enough data 
$ has been removed to allow its write request to be satisfied. If 
$ the size parameter is zero, then the pipe will be created with the 
i default size (this size is unknown at this time but will likely be 
§ in the range of 1 to 8 kb.) 


# A pipe will be deleted when all users close the handles. If there 
! are two process communicating by a pipe and the process reading 
$ the pipe ends, the next DosWrite to that pipe will return the 
+ “write to a broken pipe” return code. 


+ The value in PipeSize is an advisory size in that that may not be 
+ the actual amount of memory allocated by the system for the pipe 
+ buffer. If a size of zero is specified, then the default size is 
+ used for the buffer. 
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2.1.2 Named Pipes 


Named pipes provide I/O between arbitrary (unrelated) processes. Anonymous 
pipes provide I/O only between a parent and descendent (related) process. 


Without named pipe 1/0, the only way two 
communicate is via shared memory, or via queues which depend on passing 
references to shared memory. This means that inter-process communication 
necessitates undesirable coupling between unrelated processes, and such 
coupling may be impractical to achieve if the processes are supplied by 
independent vendors (e.g., a database service process and a user interface 
process). 


unrelated processes in OS/2 can 


Anonymous pipes, unlike other file system resources, cannot be virtualized 
across a network. Named pipes can be virtualized exactly like files (i.e., 
it is possible to write a network requester for named pipes). Allowing pipe 
1/O to work across a network the same way that file I/O can is both 
desirable for architectural consistency and valuable for application 
development. 

These are the error codes specific to Named Pipes API. These calls may also 
return standard OS/2 error codes. 


* ERROR_BAD PIPE (230) - Non-existant pipe or bad operation. 


* ERROR_PIPE BUSY (231) ~- Pipe is busy. 
* ERROR_BROKEN PIPE (232) - Other end of pipe is closed. 
* ERROR_PIPE_NOT CONNECTED (233) - Pipe was disconnected by server. 


* ERROR_MORE_DATA (234) - More data is available. 
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Named Pipe Function Call Summary 

DosCallNmPipe Perform a “procedure call" transaction via a named pipe. 
DosConnectNmPipe Waits for a new client to open a named pipe. 
DosDisConnectNmPipe Forces a named pipe closed. 

DosMakeNnPipe Create a named pipe. 

DosPeekNmPipe Read named pipe contents without removal. 
DosQNmPipeHandState Query named pipe specific handle state information 
DosQNmPipeInfo Query named pipe information 

DosRawReadNmPipe Read a named pipe directly. 

DosRawWriteNmPipe Write to a named pipe directly. 

DosSetNmPFHandInfo Set named pipe specific handle state information 


DosTransactNmPipe Perform a transaction to a message pipe. 


DosWaitNmPipe Waits for an available named pipe instance. 
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# 
] 
4 
# 2.1.2.1 Named Pipe Function Calls 
: # 
§ 
# 2.1.2.1.1 DosCallNmPipe:- Perform a procedure cal] via a message pipe.: 
if Purpose Provide a “procedure cal)" transaction via a message pipe. # 
i 
# Format. Callilny Sequence: g 
i 
| EXTRN DosCallNmPipe:FAR 
i PUSH@ ASCIIZ FileName ; Pipe name $ 
i PUSH®@® OTHER InBuffer ; Write buffer address 
| PUSH WORD InBufferLen ; Write buffer length i 
f PUSH@ OTHER OutBuffer ; Read buffer address i 
# PUSH WORD OutBufferLen ; Read buffer length 
| PUSH@ WORD BytesOut ; Bytes read (returned) | 
# PUSH DWORD TimeOut ; Maximum wait time 
| CALL DosCallNmPipe 
q 
i where FileName is the ASCIIZ name of the pipe to be opened./f 
f Pipes are named \PIPE\FileName t 
# inBbutfer is address of buffer to write to the pipe. 
# InHulferLen is the number of bytes to be written. # 
] 
] OutBuffer is address of buffer for returned data. 
§ 
i] OutHhufferLen is the maximum size (number of bytes) of 
a returned data. ¥} 
¥ BytesOut is where the system returns the number of bytes/# 
# actually read (returned). 
f 
f TimeOut is the maximum time to wait for pipe 
# availability. \é 
# Returns: IF ERROR (AX not = 0) # 
3 AX = Error Code: 
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* ERROR _FILE_NOT FOUND 
* ERROR_BAD PIPE 

* ERROR PIPE _BUSY 

* ERROR _PIPE_NOT CONNECTED 


. ERROR _ MORE DATA 


This routine has the combined effect on a named pipe of DosOpen, 
DosTransactNmPipe, DosClose. It provides a very effiecient means 
of implementing local and remote procedure-call (RPC) Intertaces 
between processes. 


DosConnectNmPipe:- Waits for a new client to open a pipe.: 


Enables a new client to obtain handle-based access to a named pipe 
through DosOpen. 


Calling Sequence: 


EXTRN DosConnectNmP ipe : FAR 


PUSH WORD Handle ; Pipe handle 
CALL DosConnectNmPipe 


where Handle is the handle of the named pipe returned by 
DosMakeNnmP ipe. 


Returns: IF ERROR (AX not = 0} 
AX = Error Code: 
* BRROR_BAD PIPE 
* ERROR_PIPE NOT CONNECTED 
eg ERROR_BROKEN PIPE 


* ERROR_INTERRUPT 
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Remarks DosConnectNmPipe causes a newly made or disconnected named pipe 
to enter a listen state that will accept a DosOpen from a client 
(DosOpen to a pipe not in the listen state will fail). If the 
client end of a pipe is currently open, DosConnectNmPipe returns 
immediately and has no effect. If the client end is not open, 
DosConnectNmPipe either waits until it is open (if blocking mode 
is set) or else returns immediately with error PIPE _NOT_CONNECTED 
(if non-blocking mode is set). If the pipe was previously opened 
but has been closed by the client and not yet disconnected by the 
server, DosConnectNmPipe always returns  ERROR_BROKEN PIPE. 
Multiple DosConnectNmPipe can be issued in non-blocking mode; the 
first one puts the pipe into listen state (if it is not already 
open or closing) and subsequent ones simply test the pipe state. 
If DosConnectNmPipe is called by the requestor (client) end of 
the pipe, the error BAD PIPE is returned. If the wait (in 
blocking mode only) for the client open was interrupted, the error 
INTERRUPT is returned. 


2.1.2.1.3 DosDisConnectNmPipe:- Forces a named pipe closed.: 


Purpose Forces a named pipe to close. 
Format Calling Sequence: 


EXTRN DosDisConnectNmPipe :FAR 


PUSH WORD Handle ; Pipe handle 
CALL DosDisConnectNmPipe 


Handie is the handle of 


DosMakeNnP ipe. 


where the named pipe returned by 


Returns: IF ERROR (AX not = QO) 


AX = Error Code: 


. ERROR_BAD PIPE 


pipe is currently opened, 
it closed (the client gets an error 
Note that this may discard data 
the client. If the client end is 


Remarks If the client end of the 
DosDisConnectNmPipe forces 
code on its next operation). 


which has not yet been read by 
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currently closing (DosClose has been issued), DosDisConnectNmPipe 
acknowledges the close and makes the pipe available to be 
reopened. A client that gets forced off a pipe by a 


DosDisConnectNmPipe must still issue DosClose to close its end of 


the pipe. 
2.1.2.1.4 DosMakeNmPipe - Create a named pipe.: 
Purpose Creates the specified named pipe and returns its handle. 
Format Calling Sequence: 
) 
EXTRN DosMakeNmP ipe :FAR 
PUSH@ ASCIIZ FileName 7; Pipe name 
PUSH@ WORD PipeHandle ; Returned pipe handle 
PUSH WORD OpenMode > DOS open mode of pipe 
PUSH WORD PipeMode 7 Pipe open mode 
PUSH WORD OutBufSize ; Advisory outgoing buffer size 
PUSH WORD iInBufSize ¢ Advisory incoming buffer size 
PUSH DKORD TimeOut ; Timeout for DosWaitNmPipe 
CALL DosMakeNmP ipe 
where FileName is the ASCIIZ name of the pipe to be opened. 
Pipes are named \PIPE\FileName 
PipeHandle is where the system returns the handle of the 
named pipe that is created. 
OpenMode is the Dos OpenMode of the named pipe and 
consists of the following bit fields. They are the: 
* Inheritance flag 
* Write-through flag 
* Access field 
The bit field mapping is shown as follows: 
Open Mode 5432109876543210 
bits Ow***e® & *# wT OOO*AAA 
W File Write-through 
The file is opened as follows: 
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If W = 0; Write-behind to remote pipes 
is allowed. 
If W = 1; Write-behind to remote pipes 
is not allowed. 
Write behind only has meaning tin the case of 
remote pipe. OS/2 will in certain cases locally 
buffer data that is written to a pipe, and not 
send it across the net to the remote end until a 
future time. The Write through bit lets the 
application prevent this behavior, so that data 
will be sent across the net as soon asit is 
written by the application. 
I Inheritance Flag 
If I = 0; Pipe handle is inherited by a 
spawned process resulting 
from a DosExecPgm call. 
If I = 1; Pipe handle is private to the 
current process and cannot be 
inherited. 
This bit is not inherited by child processes. 
AAA Access Mode 
The pipe access is assigned as follows: 
If A = 000; In-bound pipe (client to server) 
= 001; Out-bound pipe (server to client) 
= 010; Full duplex pipe (server to/from cli 
Any other value is invalid. 
* Bit is not applicable. 
PipeMode defines the pipe-specific mode parameters and 
consists of the following bit fields. They are the: 
* Blocking 
* . Type of named pipe 
. Read mode 
* Instance count 
The bit field mapping is shown as follows: 
Pipe Mode 543210987654321 0 
bits B* * * TT RR J----ICount---] 
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# B Blocking: 
$ The pipe is defined as follows: 
# Tf B = O; Reads/Writes block if no data 
# available. 
# If B = 1; Reads/Writes return immediately 
# if no data available. 
# Reads normally block until at least partial data 
i can be returned. Writes by default block until 
# all bytes requested have been written. 
# Non-blocking mode (B=1) changes this behavior as 
# follows: 
? 1. DosRead will return immediately with 
# BytesRead=0 if no data is available. 
# 2. DosWrite will return immediately with 
# BytesWritten=0 if no data is available. 
$ Otherwise, the entire data area will be 
# transferred. 
# TT Type of named pipe. 
If TT = 00; Pipe is a byte stream pipe. 
= 01; Pipe is a message stream pipe. 

a All writes to message stream pipes record the 
# length of the write along with the written data 
# (see DosWrite). The first two bytes of each 
at) message represents the length of that message 
i and is called the message header. A header of 
# all zero’s is reserved. Zero length messages 
a are not allowed (because OS/2 no-ops zero-length 
i I/Os). 
i RR Read Mode 
# If RR = 00; Read pipe as a byte stream. 
# = 01; Read pipe as a message stream. 
# Message pipes can be read as byte or message 
? Streams, depending on the _ setting of RR. Byte 
i Pipes can only be read as byte streams (see 
# DosRead) . 
# ICcount Byte wide (8-bit) count to control pipe 
t instancing. Referred to as Instance Count. 
P| When making the first instance of a named pipe, 
i ICount specifies how many instances can be 
# created: 
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bl 1 ==> this can be the only instance (pipe is 
unique), 


* -] ==> the number of instances is unlimited, 


* 0 ==> reserved value. 


Subsequent attempts to make a pipe will fail if 
the maximum number of allowed instances already 
exists. The ICount parameter is ignored when 
making other the first instance of a pipe. When 
multiple instances are allowed, multiple clients 
can simultaneously DosOpen to the same _ pipe 
name and get handles to distinct pipe instances. 


OutBufSize is an advisory to the system of the number of bytes to 
allocate for the out-going buffer. 


InBufSize is an advisory to the system of the number of bytes to 
allocate for the incoming buffer. 


default value for the timeout parameter to 
DosWaitNmPipe. This value may be set only at the creation of the 
first instance of the pipe name. If at that time the value is 
zero, a system wide default value (50 ms) will be chosen. 


TimeOut is the 


IF ERROR (AX not = 0) 
AX = Error Code: 
* ERROR_PATH NOT FOUND 
* ERROR _INVALID PARAMETER 
* ERROR PIPE_BUSY 
* ERROR _OUT_OF_STRUCTURES 


*  ERROR_NOT ENOUGH MEMORY 


How the full duplex pipe works: 


The concept is that one process uses DosMakeNmPipe to create a 
named pipe, and then waits for another process to open the pipe by 
name via DosOpen. The pipe maker is called the “serving” end of 
the pipe. The pipe opener (client) is called the “requesting” 
end. 


opened, each end has a 


Once a pipe has been made and successfully 
its handle from 


handle associated with it. The serving end gets 
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DosMakeNmPipe. The requesting end gets its handle from DosOpen. 
Unlike for anonymous pipes, each end can both read and write its 
one handle. Anything that one end writes the other end will be 
able to read and vice versa. This is because there are in fact 
two pipe buffers for a named pipe, one for each direction of flow. 


Process A Process B 


(serving end) Pipe (requesting end) 
Buffers 
s dleceaetetetenetetanar + 
DosWrite ------ >})3)703270)7 ------ > DosRead 
ten-He a= + 
tenn 2-—-- ~~ + 
DosRead €s-- = } 3) ]) J J] ) ] <a DosWrite 
tana + | 


] ) 
Process A uses handle Process B uses handle 
from DosMakeNmP ipe from DosOpen 


Here is an example to show how a named pipe is created, 
and read/written by each end. 
explain the role of the 
calls. 


opened, 
Comments follow the example that 
DosConnectNmP ipe/DosDisConnectNmP ipe 


Process A 
(serving end) 


Process B 
(requesting end) 


/* First make a pipe */ 
DosMakeNmP ipe (“\pipe\foo", handlel) 
} 


Vv 
/* Wait for requester to open it */ 
DosConnect NmP ipe (handlei) 


/* Open pipe */ 


/* Read client request */ 
DosRead (handlel, buffer) 


: /* Write request to pipe 
aaa DosWrite (handle2, buf fer2) 

J 

] /* Read response from pipt 


/* Process client’s request */ 
) 
} 


Vv 


DosRead (handle2, buffer2) 
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/* Write response */ 
DosWrite (handlel, buffertl) 


Vv 
/* Stop using the pipe * 
DosC lose (handle2) 


V 
/* Prepare for next client */ 
DosDisConnectNmPipe (handlel) 


v 
/* Wait for another client */ 
DosConnect NmP ipe (handle1l) 


the role of the 
calls versus 


It is important. to understand 
DosConnectNmP ipe/DosDisConnectNmPipe 
DosOpen/DosClose. 


A serving process creates a named pipe and then must wait for a 
client to open it. The DosConnectNmPipe accomplishes this. It 
takes the handle for the pipe and waits for an open to happen (or 
returns status indicating that the pipe is already open). Until 
some client opens the pipe via DosOpen, it is in the “listening” 
state. 


Once a pipe is open, the serving and requesting ends have a 
conversation using DosRead and DosWrite (or DosTransactNmPipe, 
which performs DosWrite followed by DosRead on the pipe). The 
pipe acts like a full duplex channel between the two processes. 


At some point, the requesting end may choose to close its end of 
the pipe, in which case the serving end will eventually get: 


1. An BOF on a future read that finds the pipe empty or 


2. The error BROKEN PIPE when it tries to do a write to the pipe. 


The serving end must "acknowledge" the client’s close of the pipe 
by doing a DosDisConnectNmPipe. The serving end's handle will now 
be invalid for I/O until another DosConnectNmPipe is done to await 
the next DosOpen. Until a close has_ been acknowledged by 
DosDisConnectNmPipe, repeated reads of the pipe by the serving end 
will continue to return EOF, and other requesters that attempt to 
open the pipe will get error PIPE BUSY. 


These rules make sure that the serving end has a well controlled 
way to know when the requesting end of the pipe has been closed, 
and to let the serving end control when it is acceptable for 


another requester to open the plpe. 
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The serving end can destroy a named pipe at any time. It uses 


the following OS/2 call sequence to do this: 
* DosDisConnectNmPipe (handlel) 


* DosClose (handlel) 


DosDisConnectNmPipe will dissociate the requesting end’s file 
handle from the named pipe data structures and allow DosClose to 
terminate the last reference to the pipe. 


The serving end's DosClose frees its pipe handle, however, the 
pipe buffer will not be released until the requesting end has also 
issued a DosClose on its handle to the pipe. In this case, the 
requester will get the error PIPE _NOT CONNECTED on its next 
DosRead or DosWrite, and will have to issue the DosClose. 


The serving end may also issue a DosClose to free its pipe handle 
without a preceding DosDisConnect. The effect of this is that the 
requestor can read any of the remaining data in the pipe buffer 
without getting the error PIPE_NOT CONNECTED on every DosRead 
operation. 


The concepts of disconnecting and closing are separated so that 
the serving end can create a pipe and reuse it serially for 
conversations with different requesters. Without this concept, 
the serving end would have to delete and recreate the pipe for 
each conversation. 


DosPeekNmPipe:- Peek into a named pipe.: 


# Purpose Read pipe without removing the read data from the pipe. 
# Format Calling Sequence: 
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EXTRN DosPeekNmPipe:FAR 
PUSH WORD Handle ; Pipe handle 
PUSH@ OTHER Buffer ¢ Address of user buffer 
PUSH WORD BufferLen ; Buffer length 
PUSH@ WORD BytesRead ; Bytes read 
PUSH@ DWORD BytesAvail ; Bytes available 
PUSH@ WORD PipeState ; Pipe state 
CALL DosPeekNmPipe 
where Handle is the handle of the named pipe returned by 
DosMakeNmPipe or DosOpen. 
Buffer is address of the output buffer. 
BufferLen is the number of bytes to be written. 
BytesRead is where the system returns the number of 
bytes actually read. 
BytesAvail is a 4-byte buffer where the system returns 
the number of bytes that were actually available. This 
buffer is structured as follows: 
* 2 bytes - Bytes left in pipe (including message 
header bytes) 
* 2 bytes - Bytes left in current message (zero for a 
byte stream pipe) 
PipeState is where the system returns a value 
representing the state of the named pipe. 
* If value=l1, the state of the pipe is Disconnected 
x If value=2, the state of the pipe is Listening 
" If value=3, the state of the pipe is Connected 
® If value=4, the state of the pipe is Closing 
Returns: IF ERROR (AX not = 0) 
AX = Error Code: 
* ERROR_BAD PIPE 
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* ERROR PIPE NOT CONNECTED 
Remarks DosPeekNmPipe acts like DasRead except as follows: 

1. The bytes read are not removed from the pipe. 

2. The peek may return only part of a message (that part 
currently in the pipe), even if the size of the peek would 
accommodate the whole message. 

3. DosPeekNmPipe never blocks, regardless of the blocking mode. 

4. Additional information about the status of the pipe and 
remaining data are returned., The caller can use this, for 
example, whether the peek returned all of the current message 
or whether the pipe is at EOF (pipe is at EOF when there are 
no bytes left in the pipe and Status is Closing or 
Disconnected). 

PipeState is where the system returns the state of the pipe 

(Disconnected, Listening, Connected, Closing). 

The four states of a named pipe are defined as follows: 

* Disconnected - after a DosMakeNmPipe or a DosDisConnectNmPipe. 
- Indicates that the pipe has no current requesting end and 

that it is not willing to accept an open. The serving end 

must issue DosConnectNmPipe to put the pipe into the 

listening state before an open will be accepted. A pipe 

will be in the disconnected state 

1. Immediately after the DosMakeNmPipe but before the 
first DosConnectNmPipe or 

2. Immediately after a DosDisConnectNmPipe but before the 
next DosConnectNmPipe. 

* Listening - after a DosConnectNmPipe. 

- Puts pipe into a state where it will accept a DosOpen from 
a requester. A pipe not in Listening state cannot be 
opened (DosOpen will return “pipe busy"). 

* Connected - after the first DosOpen to the pipe. 

- Indicates that a requester has DosOpened the pipe. The 
serving and requesting ends are able to do I/O to the pipe 
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# (ie, there are valid handles for both ends). # * Instance count 
# The bit field mapping is shown as follows: 
* Closing - after the last DosClose to the pipe from either the 
server or requester end. # Pipe Mode 5432109876543210 
3 bits BE* * TTRR J----ICount---] 
i - The requesting end of the pipe has issued DosClose for all 
| dups of the handle it had to the pipe, i.e., thela B Blocking: 
# requesting end of the pipe is closed. The serving end 
# will get EOF on reads to the pipe after it has}a The pipe is defined as follows: 
# successfully read all buffered data; on writes, serving 
i end will get error BROKEN PIPE. The Serving end mustjf If B = 0; Reads/Writes block if no data 
# issue DosDisConnectNmPipe or DosClose to acknowledge the]# available. 
# close of the requesting end. I£ DosDisConnectNmPipe is]# If B = 1: Reads/Writes return immediately 
# used, the pipe can be reused by issuing DosConnectNmPipe, j! if no data available. 
# which allows another requester to open it. If DosClose is ’ 
i used, the pipe is deallocated. # Reads normally block until at least partial data 
# can be returned. Writes by default block unti! 
# all bytes requested have been written. 
# Non-blocking mode (B=1) changes this behavior as 
# follows: 
# 2.1.2.1.6 DosQNmPHandState - Query Named Pipe Handle State: i 1. DosRead will return immediately with 
# BytesRead=0 if no data is available. 
# Purpose Return named pipe~specific handle state information. 
# 2. DosWrite will return immediately with 
# Format Calling Sequence: # BytesWritten=0 if no data is available. | 
§ Otherwise, the entire data area will be 
# transferred. 
4 EXTRN DosQNmPHandState:FAR 
# E End-point of named pipe. 
f PUSH WORD Handle ; Pipe handle 
ff PUSH@ WORD PipeHandleState ; Pipe handle state # If E = 0; Handle is the client end of a named pip 
# CALL DosQNmPHandState # *« 1; Handle is the server end of a named pip} 
# TT Type of named pipe. 
$ where Handle is the handle of the named pipe returned by|# If TT = 00; Pipe is a byte stream pipe. 
| DosMakeNmPipe or DosOpen. # = 01; Pipe is a message stream pipe. 
# PipeHandleState is the named pipe handle state and/[# RR Read Mode 
# consists of the following bit fields. They are the: 
# If RR = 00; Read pipe as a byte stream. 
# * Blocking # = O01; Read pipe as a message stream. 
i . Server or requestor end 
¥ Icount Byte wide (8-bit) count to control pipe 
? * Type of named pipe # instancing. Referred to as Instance Count. 
4 When making the first instance of a named pipe, 
$ * Read mode i ICount specifies how many instances can be 
i created: 
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* 1 ==> this can be the only instance (pipe is 


unique), 
Ls -1 ==> the number of instances is unlimited, 
* 0 ==> reserved value. 
Returns: IF ERROR (AX not = QO) 
AX = Error Code: 
n ERROR_BAD PIPE 
* ERROR_PIPE_NOT CONNECTED 
At the serving end, the values returned by DosQNmpHandState are 
those originally established by DosMakeNmPipe or a subsequent 
DosSetNmPHandState. For the client end, the values returned are 
those originally established by DosOpen or a subsequent 
DosSetNmPHandState. 


2.1.2.1.7 DosQNmPipeInfo - Query a named pipe’s Information: 


Purpose Returns information for a named pipe. 
Format Calling Sequence: 
EXTRN DosQNmPipeInfo:FAR 
PUSH WORD Handle ; Pipe handle 
PUSH WORD InfoLevel ; Pipe data required 
PUSH@ OTHER InfoBuf ; Pipe data buffer 
PUSH WORD InfoBufSize ; Pipe data buffer size 
CALL DosQNmPipeInfo 
where Handle is the handle of the named pipe returned by 
DosMakeNmPipe or DosOpen. 
InfoLevel is the level of the pipe information required. 
Level ‘1° file information is returned in the following 
format: 
* 2 bytes - Actual size of buffer for outgoing 1/0 
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* 2 bytes - Actual size of buffer for ingoing I/o 


* 1 byte - Maximum allowed number of pipe instances 
* 1 byte - Current number of plpe instances 

* 1 byte - Length of pipe name 

* Asciiz - Name of pipe (including \\ComputerName 


{£ remote) 


InfoBuf is the storage area where the system returns the 
requested level of named pipe information. 


InfoBufSize is the length of InfoBuf. 
IF ERROR (AX not = 0) 

AX = Error Code: 

* ERROR BUFFER_OVERFLOW 


- DosQNmPipeInfo 
InfoBuf 


returns whatever will fit in 


*  ERROR_INVALID_LEVEL 


* ERROR_BAD PIPE 


# 2.1.2.1.8 DosRawReadNmPipe:- Direct (raw) read named pipe: 


# Purpose Read bytes directly from a named pipe, regardless of whether it is 
q a message or a byte stream pipe. 
# Format Calling Sequence: 
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$ EXTRN DosRawReadNmP i pe: FAR 8 EXTRN DosRawWr iteNmPi pe :FAR 
é PUSH WORD Handle ; Pipe handle $ PUSH WORD Handle ; Pipe handle 
8 PUSH@® OTHER Buf fer : Buffer address é PUSH@ OTHER Buffer ; Buffer address 
a PUSH WORD BufferLen ; Buffer length 8 PUSH WORD BufferLen : Buffer length 
t PUSH@ WORD BytesRead ; Bytes read (returned) | PUSH@ WORD BytesWritten ; Bytes written (returned) 
| CALL DosKawReadNm? ipe a CALL DosRawWriteNmPipe 
] where Handle jis the handle of the named pipe returned byl# where Handle is the handle of the named pipe returned by 
| DosMakeNalipe or DosOpen. a DosMakeNmPipe or DosOpen. 
| Buffer is address of butfer to receive the data from[# Buffer is address of data buffer to write to the pipe. 
a the pipe. 
§ BufferLen is the number of bytes to be written. 
a BufftercLen is the number of bytes to be read. 
§ BytesWritten is where the system returns the number of 
‘ HytesRead is where the system returns the number of]! bytes actually written (returned). 
] bytes actually read (returned). 
| Returns: IF ERROR (AX not = 0) 
| Returns: IF ERROR (AX not «= 0} 
+2 AX = Error Code: 
] AX = Error Code: 
a * ERROR_BROKEN PIPE 
a . ERROR_PIPE_NOT_CONNECTED 
] * ERROR_PIPE NOT CONNECTED 
# Remarks 
#@ Remarks The data in Buffer should include message headers if {t is a 
| For a byte pipe, this 1s exactly like DosRead. for a message jf message pipe. Thia call ignores’ the blocking/nonblocking state 
| pipe, this is exactly like DosReading the pipe in byte read mode, }f and always acts in a blocking manner--it returns only after a} 
| except message headers will also be returned in the buffer (note[é bytes have been written. 
6 that message headers will always be returned in total--never split 
| at a byte boundary). 8 This function will not be documented to users. 
i] This function will not be documented to users. 
# 2.1.2.1.10 DosSetNmPHiandState ~ Set Named Pipe Handle State: 
#@2.1.2.1.9 DosRawWriceNmPipe:- Direct {14w) weite named pipe: & Purpose Return named pipe-specific handle state information. 
§@ Purpose Put bytes directly into a named pipe, regardless of whether it is/@ Format Calling Sequence: 
| a message or 2 byte stream pipe. 
§ Format Calling Sequence: 
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EXTRN DosSetNmPHandSt ate :FAR 
PUSH WORD Handle ; Pipe handle 
PUSH WORD PipeHandieState ; Pipe handle state 
CALL DosSetNmPHandState 
where Handle is the handle of the named pipe returned by 
DosMakeNmPipe orf DosOpen. 
PipetandieState is the named pipe handle state and 
consists uf the following settable bit fields. They are 
the: 
: Blocking 
. Read mode 
The bit field mapping ts shown as follows: 
Pipe Mode 543210980765 43210 
bits Bee*nrree RRGOOHO 00000 
B Blocking: 
The pipe is defined as follows: 
if B = O; Reads/Writes block if no data 
avai lable. 
lf 8 += 1; Reads/Writes return immediately 
if no data available. 
Reads normally block until at least partial] data 
can be returned. Writes by default block until 
all bytes requested have been written. 
Non-bluocking mode (B-1) changes this behavior as 
fot lows: 
1. DosKead~ will return immediately with 
HytesRead:0 if no data is available. 
2. DuoswWrite will retucn immediately with 
BytesWritten-0 af no data is available. 
Otherwise, the entire data area will be 
transferred. 
RR Read Mode 
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Format 
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If RR = 00; Read pipe as a byte stream. 


= 01; Read pipe as a message stream. 


Returns: IF ERROR (AX not = Q) 
AX = Error Code: 
* ERROR_INVALID PARAMETER 
* ERROR_BAD_PIPE 


* ERROR_PIPE NOT CONNECTED 
Note that only the read mode (byte vs message) 


blocking/nonblocking mode of a named pipe can be changed. 


Perform a transaction (write followed by a 
pipe. 


read) on 


Calling Sequence: 


EXTRN DosTransactNmPipe:FAR 


PUSH WORD Handle 

PUSH®@ OTHER InBuf fer 
PUSH WORD InBufferLen 
PUSH@ OTHER Out Buffer 
PUSH WORD Out BufferlLen 
PUSH@ WORD BytesOut 
CALL DosTransactNmPipe 


Pipe handle 

Write buffer address 
Write buffer length 
Read buffer address 
Read buffer length 
Bytes read (returned) 


Se we Bp Be Bp Be 


where Handle is che 


DosMakeNmPipe or DosOpen. 


InBuffer is address of buffer to write to the pipe. 


IntufferLen is the number of bytes to be written. 


OucBuffer is address of buffer for returned data. 
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OutBufferLen = is 
returned data, 


the maximum size (number of bytes) of 


HytesOut is where the system returns the number of bytes 
actually read (returned). 


Returns: IF ERROR (AX not - 0) 


AX + Error Code: 

¥ ERKOR BAD PIPE 

. ERROR PIPE HUSY 

® EHROK PIPE NOT CONNECTED 


: ERROR MORE DATA 


This provides an optimum way to implement 
dialogs. DosTransactNmPipe will fail If the pipe currently 
contains any unread data oc is not in message read mode. 
Otherwise the call will write the entire InBuffer to the pipe and 
then read a response from the pipe into the OutBuffer. The state 
of blocking/nonblock ing has no affect on this 
cali--DosTransactNmPipe does not return until a message has been 
read into the OutBuffer. Jf the OutBuffer is too small to contain 
Lhe response message, the error MORE DATA will be returned as 
described for DosRead. 


transact ion-oriented 


2.1.2.1.12 DusWaitNmPipe:- Wait for an available named pipe instance.: 


Purpose Waits for the availability of a named pipe instance. 
Format Calling Sequence: 

LXTRN DosWaitNmP ype sb AK 

PUSH@ ALCTIZ FileName i Pipe name 

PUSH DWOKD = TimeQut ; Maximum wait time 

CALL DusWaitNmPi pe 

where FileName is the ASC1Ii2 name of the pipe to be opened. 
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Pipes are named \PIPE\FileName 


TimeOut is the maximum time (milliseconds) to wait for 
the named pipe to become available. If a zero value is 
used, the default value specified at DosMakeNmPipe = cime 
will be used. If a‘’~-l"’ value is used, an Iindctinite 
wait will be entered. 


Returns: IF ERROR (AX not = 0) 


AX ~ Error Code: 
® ERROR FILE NOT_FOUND 
a ERROR _PIPE BUSY 


* ERROR INTERRUPT 


DosWaitNmPipe allows an application to wait for a server on a pipe 
for which all instances are currently busy. This call should be 
used only when ERROR_PIPE BUSY is returned from a DosOpen cal}. 
The call will wait up to Timeout milliseconds (or a default time 
if Timeout is zero) for a pipe of the name given to become 
available. When a pipe instance becomes available, it will be 
given to the highest priority waiting process. Waiting processes 
of equa] priority will be given an available pipe instance based 
on longest time spent waiting for the named pipe. 


2.1.3 I/O Services 


OS/2 {TM) provides 
syslem calls. 
the device, such 
respectively. 
in addition, the file system API may be used to 
such as LPT] ox COM). 


device, 


2.0 Functional] Characteristics 


access to the major character and block devices through 
Some devices may be accessed through system calls specific tu 
as the KBD and VIO calls for the keyboard and display, 
A device such as the disk is accessed via file system AP!. 
access any named characte: 
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2.1.4 ANSI Support for Video and Keyboard 


The ANSI commands {(ESC[...h) to set mode must set, in both OS/2 and DOS 
modes, the video into the new video mudes of the EGA and ISM PS/2 (TM) 
models 50, 60 and 60 toc these codes: 


14 is 640x200 color 
15 ts 640x350 mono 
640x350 color 
17 1s 640x480 color 
18 is 640x480 color 
19 is 320x200 color 


> 2 8® 8. B&B ® 
— 
i- a) 
~ 
a 


For enhanced keyboards, Extended Keys (0OE0H low bytes) should be 
supported as distinct keys. PC-bOS will provides this with a /X switch for 
DEVICE=ANSI].SYS. If /X is omitted, Extended Key vaives are supported as 
normal keys (O00H low bytes). OS/2 should provide this support in OS/2 and 
DOS modes and consider PC-DOS compat ibility. 


2.1.4.1 Device and File Handles 


Many system calls use a parameter called a handie A handle is a 16-bit value 
which is used to refer to a particular device or file. 


2.1.4.2 Handling of 1/0 


A user process may perform 1/0 to a character device in one of two modes: 
raw and cooked. These modes may be set by the user process through the 


IOCTL facility. The device drivers provided with OS/2 that support raw and 


cooked mode are: 


* Keyboard 


In taw mode, data is transferred exactly as it appears and for the length 


chat the user requested. In cooked mode, data may be edited, buffered, 


and/or translated by the OS/2. The operations that the OS/2 performs for 


cuoked mode 1/0 are as listed below. 


. For a read in cooked mode: 
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- The characters “Cc, 
specially. 


“Break, “S, “*P, and “PrtScrn are handled 


- The OS/2 provides buffered input with editing via function keys. 

- The data is read until the first *M or ENTER key is seen. This 
means that the length of the read data may be less than the 
requested length. Note that the data is always terminated with the 
byte sequence ODH OAH. 

~ It *Z is encountered, no further data is read. 


- The data is echoed when read. 


- Tabs are expanded into 8-character boundary spaces upon echo, but 
left as O9H in the buffer. 


* For a write in cooked mode: 
- The *S is interpreted for flow control. 
- The “P or “PrtScrn toggles printer echoing. 
- The *C or “Break generates a signal for control-break handling. 
~ Tabs are expanded to 8-character boundaries and filled with spaces. 


~ Ascii character codes less than 20H are preceded with a caret (*) 
and 40H is added to the codes. 


- Output is performed up to (but not including) a “2 or the length ot 
the request. The number actually written may be less than the 
Number requested. 


A user process performs 1/0 to a block device strictly in raw mode. Data is 
transferred without interpretation or translation. 


2.1.4.3 ASCIIZ Strings 
Several function calls accept an ASCIIZ string as input. This consists of 
an ASCII string terminated by a byte of binary zeros. 


World Trade Considerations: ASCIIZ strings may be composed of mixed single- 
and double-byte characters, and may be used in the following cases: 


* filename and filename extension 
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* path name . 


. directory name 


2.1.4.4 Filename Specification 


The specification of a filename is dependent on the file system. The OS/2 
standard filename consists of drive specifier, pathname, filename = and 
extension. The only requited part is the filename. All other parts are 
optional. The format is as follows - hp2.|(D:] [pathname] fi lenamef{.ext) 


Drive Specifier - hp2.D: This is an optional parameter to specify the 
logicat drive. ‘D*’ can be any drive letter. If this parameter is not 
Specified, the current drive is used. NOTE: This parameter is ignored by 
the file system if a UNC specifier is also used because UNC namea have no 
associated drive Jetter. 


Pathname Specifier: (prefix) {dirclN\)i{dic2\)...idirn\) This is an optiona) 
Parameter to specify the directory. prefix: Optional leading ‘\’ or *‘\\' A 
leading '\’ starts the path from the root directory of the logical) drive. 
1f no leading ‘\’ is specified, the path starts from the current directory 
of the drive specified (or the current drive if no drive is specified). 


A leading '\\’ specifies that this is a UNC name. The entire followlkng name 
is interpreted by the network software {i.e. \\server\share\dir...\file). 
UNC paths always start from the root directory of the server share point. 


dir\: Successive directories to be searched. ‘.' and ‘*..° have special 
meaning. °.’ means the current directory. ‘..* means the parent directory. 


Filename: fillename[{.ext] This is to specify the filename or directory. 
Note: Throughout this text ‘\‘ has been used to denote the path separator 
Character. ‘’\‘ and ‘/* are interchangeable. Some internal and external 


commands use ‘°'/* for specifying options and must have ‘\* as the path 
separator, but the file system dues support '/' as a path separator. 
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2.1.4.5 File Allocation Table (FAT) Type Determination 


The FAT file system uses the FAT to map a file’s allocation of disk space. 


The first two entries in the FAT map a portion of the directory; these two 
FAT entries contain indicators of the size and format of the disk. The Fav 
can be ina 12-bit or a 16-bit format. OS/2 {TM) determines whether the 
disk/diskette has al2- or a 16-bit FAT format by looking at the total 
number of allocation units in the disk partition or on the diskette. 


OS/2 (TM) determines the type of FAT format (12 or 16-bit entries) by using 
the following formula: 


IF ({(TS-RS- (D*BPD/BPS) ~ (CE*SPF))/SPC) +1 >= 4086 
THEN 16-BIT PAT ' 
ELSE 12-bit FAT; 
where 
J TS = The count of the total sectors on the disk or diskette. 


* RS = The number of sectors at the beginning of the disk that are 
reserved for the boot record. DOS reserves 1 sector. 


* D » The number of directory entries in the root directory. 
* BPD = The number of bytes per directory entry. BPD is always 32. 
* BPS = The number of bytes per logical sector. 


* CF = The number of FATs per disk. For most disks CF is 2. For VDISK CF 
4a 1. 


® SPF = The number of sectors per FAT. 
« SPC = The number of sectors per allocation unit. 


The term ‘disk’ is defined to mean partition for a partitionable device, or 
that which is accessible through a drive letter. 


Fractional cluster numbers that may result from the calculation noted in the 
above formula are to be rounded downward, i.e., the fractional portion 
tcuncated. 
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2.1.4.6 Device Names 


The operating system has reserved certain names tor devices supported by the 
base device drivers and installable device drivers supplied with the 


operating system. These device names are listed as follows. 
ComMl First serial port. 

COM2 Second ceriat port. 

CLOCK $ Clock. 

CON Console keyboard and screen. 
SCKEEN$ Screen, 

KBD§ Keyboard. 

LPT1 or PRN First parallel printer. 
LPT2 Second parallel printer. 
LPT Third paraliel printer. 

NUL Nonexistent (dummy) device. 
POINTERS Pointer draw device. 


These names can be used in the DosUpen system cal} to OPEN the corresponding 
devices. Wate that these reserved device names take precedence over 
filenames; the OPEN always checks for a device name BEFORE checking for a 
filename. This means that a filename which matches a reserved device name 


can never be OPENed, since the device will be OPENed instead. 

Note: There are exceptions to some of these names being reserved. The 
device driver that supports COM! and COM2 Is installed via CONFIG.SYS. 
Removing this device driver or replacing it with a device driver that does 
not support the device names COM] and COM2, makes COMl] and COM2 no longer 
reserved in the system. Since the operating system naming convention is for 
COM] and COM2 to identify the serial ports, it is not recommended that these 
hames be used for any olher purpose. 
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2.1.4.7 Device 1/0 Services - General API 


2.1.4.7.1 DosBeep - Generate Sound From Speaker: 
Purpose Generate sound from speaker. 
Format Calling Sequence: 

EXTRN DosBeep;FAR 

PUSH WORD Frequency 3 Hertz 

PUSH WORD Duration s Length of sound 
CALL DosBeep 


where Frequency is the cycles per second {Hertz} in the cange 
25H to TFFFH. 


Duration is the length of the sound in milliseconds. 
Returns: IF ERROR (AX not = 0) 


AX = Error Code 


Remarks None. 


2.1.4.7.2 DosDeviOctel] - 1/0 Control for Devices: 


Pucpose Perform control functions on the device specified by the opened 
device handle. 
Format Calling Sequence: 
EXTRN DosDevlOCt1:FAR 
PUSHB OTHER Data ¢ Data area 
PUSH@ OTHER ParmLisc : Command arguments 
PUSH WORD Function ¢ Device function 
PUSH WORD Category i Device category 
PUSH WORD DevHandle # Specifies the device 
CALL DosDevIOcr! 
where Data is a data atea. 
ParmList is a command-specific argument list. 
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Function is the device-specific function code. 
Category is the device category. 


DevHandle 1s a device handle returned by DosOpen or a 
standard (open) device handle. 


Returns: IF ERROR (AX not - 0) 


AX = Error Code 


Remarks This function provides a generic, expandable IOCTL facility that 
replaces and makes obsolete the previous IOCTL system call. 


Nute: Some IJOCTI. functions do not require data and/or pacameters 
to be passed when the function is called. For these JIOCTLs 
DosDevIOCTL can be called with a DWORD of zero (null pointer) for 
either of the ParmList and Data area address fields. 


Refer to Bem me me ee ee ee bad on page ~~=- for 
information regarding specific 1/0 contro] commands. 


2.1.5 Extended DOS Partition Architecture 


The Extended DOS Partition consists of a collection of extended volumes 
which ase linked together by a pointer in the extended volumes’ extended 
boot record. An extended volume consists of an extended boot record = and 
one logical block device . An extended volume created within the extended 
DOS partition can be any size from one cylinder long up thru the maximun 
available contiguous space in the extended DOS partition. In OS/2 1.0, an 
extended volume cannot be larger than 32 MB due to the limitations of the 
FAT file system. However, in OS/2 1,1 this restriction has been removed 
trom the FAT file system. In OS/2 1.2 partition type O7h has been added for 
installable file systems. An extended volume cen be larger than 32 MB. Atl 
extended volumes must start and end on a cylinder boundary. An extended 
vulume will correspond to an image of a4 physical disk. The extended boot 
tecord corresponds to the master boot record at the beginning of an actual 
physical disk and the logical block device curcesponds tu the OOS partition 
that 18 pointed to by the master boot record. 


DOS boot sector if 
logical block 


Theretore the logital block device begins with a normal 
it 15 a DOS logical block device (syst ind= 1, 4, or 6). IFS 
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devices (syst ind « 7} need not start with a normal DOS boot sector. This 
logical block device must start on a track boundary and follow the extended 
boot record on the physical disk. The logical block device and the extended 
volume both end on the same cylinder boundary. 


Each extended volume will contain an extended boot record, located in the 
first sector of the disk location assigned to it. This extended boot record 
will contain the 55AAH signature id byte. This will allow programs that 
look at the extended (master) boot. record to be compatible. This extended 
boot record will also contain a partition table, which can contain only ? 
types of entries. The boot code is not critical, as the devices are not 


considered bootable. It is suggested that the boot code simply output a 


message indicating an unbootable partition if it is executed. 


The partition table portion of the extended boot records is the same as the 
Partitton table structure in the master boot record. This structure has 4 
parlition entries of 16 bytes each. The system id byte must be filled in 
for all 4 entries with one of the following values: 


Olh - DOS partition with SIZE =< 16MB 
O4h - DOS partition with 16MB < SIZE =< 32mMB 


OSh ~ maps out area assigned to the next extended volume. Serves 
as a pointer to the next extended boot record. 


O6h - DOS partition with SIZE > 32MB 
Oth - Installable File System 


If the system ID byte is O then the values in that partition table entry 
should be zeroed out. 


If OS/2 detects any other values other than Olh, O4h, or O6h it should 
ignore that entry and not attempt to install the logical block device. This 
will allow future expansion of devices in this area without problems with 
compatibility with earlier systems. 


The partition start and end fields (C,H,S) should be filled in for any of 
the 4 partition entries in an extended boot record that have one of the 
above system id bytes. This will allow a program such as FDISK to determine 
the allocated space in the extended DOS partition, as well as allow the 
device drivers to determine the physical dasd area that belongs to it. The 
partition start and end fields (C,H,S) for the partition entry that points 
to the logical block device (system id Olh, O4h, 06h, or O7h) map out the 
Physical boundaries of the logical block device and are offset relative to 
the beginning of the extended boot record that the entry resides in. The 
partition start and end fields (C,H,S) for the partition entry that points 
to the next extended volume (system id 05h) map out the physical boundaries 
of the next extended volume and are relative to the beginning of the entire 
physical disk. 
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The relative sector and number of sector fields will be set up differently 
depending on what system id byte is used. If Olh, 04h, O6h or O7h is in the 
system id field for that extended partition entry (pointer to the logical 
block device) then the relative sector field should be set up as an offset 
from (and including) the start of the extended boot record for the 
associated extended volume. The number of sectors {size) field will be 
filled in with the size of the created logical block device area, or in 
other words, the number of sectors mapped out by the start and stop 
cylinder/track/sector. fieids. The size of the extended volume can be 
calculated by adding the relative sector field and the sector size field of 
the associated extended boot record. 


If the system id byte is O5h, then the relative sector field will be the 
offset (of the NEXT extended volume) in sectors from the start of the entire 
extended DOS partition. The number of sectors field is not used in this 
tield, and should be tilled wath O0h’s. 


This architecture allows only one logical block device to be defined per 
extended boot record. Theretore, only a maximum of two partition entries at 
a time will be used in each extended boot record, an entry with system id 
byte of (Olb, O4h, O6h, os OPH) and an entry with id of O5h, which is the 
pointer to the next extended volume. Although only two entries can be used, 
a program installing these devices should not assume Chat the first 2 
entries will be the non zero entries. 


2.1.5.1 Installing Block Devices in the Extended Partition 


+ 


To install block devices, the device drivers should first install the 
primary DOS partitions on all physical drives if any exist. This will 
insure that an existing drive tecter (D:) on the 8)h drive will remain the 
same. After these devices are installed, then on the 80h drive, the drivers 
should look for the existence of the extended DOS partition. If one exists, 
then it should look at the first sector of the extended DOS partition for 
the firat extended boot record. If there is a valid system id (Ohh, 04h, 
O6h, or O7h) in any of the 4 partition entries, chen the device is installed 
and assigned the next available drive letter. This should occur before any 
CONFIG.SYS device drivers are loaded to allow FOISK to correctly display the 
drive letter when space is allucated for the drive. 


The first extendea boot record fin the extended DOS partition) ts 4 special 
Case in that it is possible that there will not be a device to be installed 
defined in the partition table. This 1s because the first device might have 
been created and then deleted at some time, but the first extended boot 
record is needed to point to the next one if one exists. Any other extended 
boot record will always have a device to be installed. 


Once a device has been installed (or the special cases above occurs), then 
the device driver should search the other partition entries for a system id 
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byte of 05h, indicating that another device (extended volume) exists. If a 
O5h is not found, chen there are no more logical block devices (extended 
volumes} in the extended DOS partition. 


If a 05h system id is found, then the start location in that partition entry 
should be read in order to find the location of the next extended boot 
record (extended volume). When it is located, it should be read in and then 
the process repeated in order to install additional devices. 


Once aji the valid devices for a physical drive have been installed, then 
the next physical drive should be examined and the entire process repeated. 


A device driver should not assume any order dependency when searching for a 
particular system id byte tn an extended boot record. All four possible 
entries in a extended boot record partition table should be searched before 
a driver decides that a particuiar system id byte does not exist. 


The extended DOS partition can only be created 1f a Primary DOS or IFS 
partition already exists on a bootable drive. A Primary DOS partition is a 
partition with a system id byte of Olh, O4h, or O6h. A Primary IES 
partition is a partition with a system id byte of O?h. If the drive is not 
bootable, then an extended DOS partition may be created without having a 
Primacy DOS partition. 


The Extended Dos Partition will start and end on a cylinder boundary. 


2.1.5.2 Creating Block Devices in the Extended DOS Partition 


To create the structure for an extended volume inthe extended DOS 
Partition, FDISK should determine if there is available space in the 
extended DOS partition and if less than 24 total devices are allocated in 
the system. The maximum number of block devices allowed is 26, and 2 are 
used by diskettes A: and B:. If a0, then the program will create an 
extended boot record at the space located, with a partition entry filled in 
with the size and location information for that logical block device. If 
this is not the first extended boot record, the program should then back up 
to the last extended boot record in the chain {as linked by the 05h 
entries), and create an partition entry in that extended boot record that 
has the size and location data for the newly created one. This action wil}! 
create the pointer required to locate the boot record just created. 


If this is the first extended boot record (in the extended DOS partition), 
only the size, type and location of the logical block device need to be put 
into a partition entry. The start of the extended DOS partition in the 
master boot cecord will serve as a pointer to this extended volume. 
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2.1.5.3 Deleting Block Devices in the Extended DOS Partition 


To delete a block device, the program should zero out the 16 byte partition 
entry that contained the system id byte that indicated the device type (Olh, 
O4h, O6h, or Oh). Also, if in che same extended boot record there exists a 
Partition entry with system id of O5Sh, indicating that another extended 
volume exists, then this information should be copied to the O5H partition 
entry of previous .extended boot record. There is one exception to this 
cule. If the logical block device deleted is at the beginning of the 
extended DOS partition, then only the parcition entry indicating the device 
type would be zeroed out. The OSh pointer information should be left in 
place. 


2.1.5.4 Layout of Block Devices in the Extended DOS Partition 
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Partition Table for Master boot record. See IBM PC 00S 3.20 
Technical Reference for layout. The 4 is the system id byte in 
the partition table that indicates a DOS partition where 16MB < 
SIZE =< 32M8, Lhe 2 is a XENIX partition, and the OSH maps the 
extended DOS partition. 


S5AAH is the signature to validate the master boot record. 


Primaty DOS area, must reside entirely in first 32mb of disk. C: 
is block device 80H, D: is block device 91H if it exists. This 
pactition has a maximum size of 32MB. 


Other operating system on disk, XENIX in this example. 


Extended boot record for extended volume that corresponds to 
logical block device O:. (This is assuming only 80h block device 
exists.) If @lh block device exists, then this would be block 
device E:. 


Logical block device D: partition table entry. This has a max size 
of 3263, which is indicated by the system id of 4. This must 
set the logical OOS block device as starting at the next 
track boundary. The O5h system id byte in the 2nd partition 
entry maps out the space allocated to the next extended volume. 
The starting cyl/sec/head in the partition entry with id of O5h is 
the location of the next extended boot record of the next extended 
volume. 


Logical block device D:. Logical DOS devices always begin with a 
DOS boot record as dues the primary DOS partition. 


Extended boot record for logical block device E:. 


Partition table entry for logical block device E:. This logical 
DOS block device is =< 16MB, as indicated by the system ID of Qlh. 
The entry with system id of O5h maps out the space allocated to 
the next extended volume. 


The system id byte of U6h indicates a logical block device > 32MB. 
This block device is indicated by a block device letter of F. 
Note also that a pointer exists to the next extended volume. 


The >32MB Fat Partition 


Partition Cable entry for tinal bOS tvogical block device. Note 
the absence of Obh id byte means thal there are no other extended 
volumes allocated in the extended DOS partition. This would have 
a block device letter of G. 
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2.1.5.5 BPB and Get Device Parameters for Extended Volumes 


For purposes of the BPB and Get Device Parameters (Generic I0CTL) an 
extended volume appears to the system as a virtual physical fixed disk. The 
extended boot record will correspond to the master boot record of a real 
fixed disk and the logical block device will correspond to the Primary DOs 
partition. 


This means that the BPB of the logica! DOS block device of the extended 
volume will describe the environment in the extended volume; which consists 
of the extended boot record and the logical) block device. The meaning ot 
the fields will be consistant to the meaning of the fields for the Primary 
DOS partition; as they relate to the entire physical disk, the primary DOS 
partition, and the master boot record. For example, the number of hidden 
sectors will be the distance from the beginning of the extended boot record 
(of the extended volume in question) to the start of the logical DOS block 
device (the DOS boot record). The number of sectors field will describe 
only the logical block device just like it normally only describes the 
primary OOS partition. 


2.1.5.6 Category 8 Generic IOCTL Commands 


The same philosophy as described above will apply to the disk Generic LOCTI. 
commands. For any logical block device of an associated extended volume; 
physical Cylinder, Head, Sector I/O will be mapped to within the extended 
volume. Cylinder 0, Head 0, Sector 1 will be mapped to the extended boot 
record. An error condition will be generated for any attempt to do C,H,5 
I/O beyond the size of the extended volume tn question. 


2.1.5.7 Type 6 Partition 


Note the following for a type 6 partition: 


« A l2- of 16-bit type FAT could be used to map it since the type of FAT 
is strictly based on the number of allocation units (clusters) and is 
the same algorithm used to detine the type of FAT (12 vs 16-bit) in OS/2 
1.0. 


. FAT cluster sizes are defined to be based on powers of 2 as for other 
DOS partition types. Assuming usage of the OS/2 FORMAT utility, the 
MINIMUM cluster size for a hard file is 2K. Cluster size and the type 
of PAT (i2 vs 16-bit) is determined by the media partition size. The 
OS/2 FORMAT algorithm is: 
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- If partition size +<]6MB 

then do; 

use 12-bit FAT; /* max 4084 entries */ 

max cluster size = 4KB; 

end; 

else do; /* partition size >16MB */ 
use 16-bit FAT; /* max 64K entries */ 

min cluster size «= 2KB; 

end; 


Note: however thdt the actual determination of the partition type is 
made based on the number of clusters on that partition (0S/2 FORMAT just 
makes sure that this is true for the <16MH and >16MB partitions. 


- lf mumber of clusters <+ 4084 
use 12-bit FAT; /* max 4084 entries */ 
else A 
use 16-bit FAT; /" max 64K entries */ 


A partition size of 128MB would require a 2K cluster size based on a 
maximum 64K allocation units (clusters). A partition size of 
129MB-256MH would require a 4K cluster size based on 64K allocation 
units (clusters). A partition size of 257MB-512MB would require an 8K 
cluster size based on 64K allocation units (clusters). 


Configuration table used by OS/2 FORMAT: 


Total #8 of Size of Sec/clus # of root dir 
sectors Partition entries 
32K 16M 8 512 
64K 32M 4 512 
256K 120M 4 512 
512K 256M 8 512 
1M 512M 16 512 
2M 1G 32 512 
4M 2G 64 512 
8M AG 128 512 


Please note that for type-6 partitions it is safe to use a non-default 
configuration, but this may be unsafe for other partition types. 


It can reside any where on the media, as the primary DOS partition 
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and/or as an extended volume within the extended DOS partition. 


The VPB parameter ‘number of sectors per FAT’ field width has been 
extended from a byte to a word in order to define a full 128KB FAT 
structure. This change affects all DOS partition types. 


In the extended volume context, type 6 > O MB. 


In the primary DOS partition context, type 6 > O MB. If the particion 
spans the 32MB boundary or starts at or beyond the 32MB boundary, it can 
be any size > O and STILL BE A TYPE 6 PARTITION. 


On behalf of a DosDevIoCt!] ‘Get Device Parameters’ call, 


- If the media is > 32MB, or is defined by a type 6 partition, the 
recommended BPB must show a 0 in TotalSectors, Ext TotalSectors must 
show the number of sectors on the media, and the double word form of 
‘tliddenSectors’ must show the number of sectors after the Master 
Boot Record to the start of the partition’s OS/2 boot record. 


2.1.5.8 Layout of Block Devices With A Type 6 Partition 


| Master Boot Record ...Note 1........] 
Power cen cnneescesae sate tr ten teatemant 


J-2...55-2.2-NOLe 2 > (2 16 {0 {0 |5S5AA] < Note 3 


Poem en tee ee oe te-t--4-- t--4----4 

{ Other operating system Partition | 
(XENI X) 1 

} Size > 32MB Note 4 i 

Pr rn ow ew nn eo ee en ee ¢ 


{ Primary DOS Partition Note 5 ] 
! DOS C: drive 32mb > Size | 


Pn nr ene e nnn etententetnetestntetataduatenentaten + 
| Free Space not allocated to any { 
| partition | 
, arr ern. tt ne eee ee ene + 


Figure 2. Example of layout of large DASD device with a type 6 partition. 


Note 1 Master boot record code, starting at Trk 000, Hd 00, Sec O01 of 


disk 90H or 81H. 


Note 2 Partition Table for Master boot record. See IBM PC DpOS 3.720 


Technical Reference for Jayout. The 2 is the system id byte in the 
partition table that indicates a XENIX partition, and the O6iI 
maps a primary DOS type 6 partition. 


ou 
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Note 3 SSAAH is the signature to validate the master boot record. 


Note 4 


Note § 


Other operating system (XENIX}) on disk. 


Primary DOS partition. C: is block device 60H, The partition 
type in this example is a 6 because it ends beyond the first 32MB 
of the disk. Note that within the scope of this definition that 
though the size of a primary DOS partition may be less than 32MB, 
because it ends beyond the first J2MB of the disk it is defined as 
a type 6. 


2.1.5.9 Layout of Block Devices With A Type 6 Partition 


ie ee eee ¢ 
1 Master Hoot Kecord ...Note 1l........ j 
lcveeecewex Be aielaiie dare tem te to--te te 4 
ba Saree cteete ae Note 2 > {6 {0 {0 |0 {SSAA} < Note 3 
tae en ne ee wenn ee we t--4¢--t--t--t----+ 


| Peimary DOS Pactititon Note 4 { 
1 DOS C: drive Size > 32mb } 


Figure 3. Example of layout of large DASD device with type 6 partition. 


Note 1 Master boot record code, starting at Trk 000, Hd OO, Sec 01 of 
disk 80H or 61H. 

Note 2 Partition Table for Master boot record. See IBM PC DOS 3.20 
Technical Reference for layout. The 6 is the system id byte in 
the partition table that indicates a DOS partition where 32MB < 
S1ZE. 

Note 3 55AAH is the signature to validate the master boot record. 

Note 4 Primary DOS acea. Owns the entice media and exceeds 32mb in size. 


C: is block device UBOH. 


2.1.5.9.1 Type ? Partition: 


Note the tollowing for a Lype / partition: 


. Partition type 7 are used fore Installable File Systems only. The 
intecnal FAT tile system should not use this partition type, since it 
will mean that older versions of PC-DOS and OS/2 will not be able to 
access the partition. 
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2.1.6 Code page support prompt. The process code page of a new program started from a 
session command prompt is set to that session's code page. 


DosSetCp sets the process code page of the calling process. The 
code page of a process is used in the following ways. First, the 
printer code page is set to the process code page through the file 
2.1.6.1 Code Page AP! system and printer spooler (the system spooler must be installed) 
when the process makes an open printer request. Calling DosSetcp 
does not affect the code paye of a printer opened prior to the 
call and does not affect the code page of a printer opened by 
another process. Second, country dependent information will, by 
2.).6.1.1 DosSetCp - Set Code Page: default, be retrieved encoded in the code page of the calling 
process. And third, a newly created process inherits its process 
Purpose DosSetCp allows a process to set its code page and the session’s code page from its parent process. 
display code page and keyboard code page. 
DosSetCp also sets, in the session to which the calling process 


Format Calling Sequence: belongs, the code page for the session’s default logical keyboard 
and automatically flushes the keyboard buffer. It also sets the 

EXTRN DPosSetCp:FAR ; display code page for the session’s logical display. This setting 

of the code page for the session's default logical keyboard and 

PUSH WORD CodePage ; Code page identifier display overrides any previous setting by DosSetCp, KbdSetCp, and 


PUSH WORD Reserved ; Reserved VioSecCp by any process in the same session. 
Call DosSetCp ;: 

The keyboard code page is switched for keyboard handle zero and 
Where CodePage is a code page identifler word that has one of the keyboard buffer is automatically flushed. The display code 


the following values: page is switched for implicit display handle zero. DosSetCp is 
for a program to initialize its code page when it begins 

. 437 1BM PC US 437 code page : execution. 

° 850 Multilingual code page 

* 860 Portugese code page ] DOSSETCP is restricted for use by VIO applications only. 

* 863 Canadian-French code page 

. 865 Nordic code page CODE PAGE CONFIGURATION 

Resecved is a reserved word and must be set to zero. Code page configuration of the system is necessary to be 


able to successfully switch between two code pages at run 


Returns if AX = 0 time. The following set of commands must be set up correctly 
in CONFIG.SYS for this purpose: 
NO error 
ELSE Command Purpose 
AX = Error Code: 
CODEPAGE Specify one or two code 
* Invalid code page page identifiers 
s Invalid parameter value the system is to set up for use. 
Remarks DosSetCp allows a program to set its code page. See CONFIG.SYS COUNTRY Specify the country code and a fully 
and the CODEPAGE command for preparing code pages for the system, specified file name. 
The first code page specified in the CODEPAGE command is the The file contains a set of country 
default system code page. The session code page of a new session! information tn the form of characters 
is set to the default system code page. A session's code page can encoded according to a code page based on 
be changed by the user with the CHCP command at the command ASCII. The system will default to the 
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COUNTRY.SYS file in the root directory of 
the boot drive if no file is specitied. 


DEVINFO Specify the keyboard layout selection and 
a fully specified file name. 
The tile contains a keyboard layout cable 
for translating keystrokes into 
characters encoded according to a code 
Page bused on ASCII. The system defaults 
to the KEYBOARD.SYS file in the root 
directory of the boot drive if no file is 
specified. 


DEVINEO Specify for the display device a fully 
Sspecttied File name. 
The file contains a video tont table for 
displaying cheracters encoded according 
to a code paye based on ASCII. The system Remarks 
does not have a detault file name. 


DEVINFO Specity for the printer device a fully 
specified file name. 
The file contains a printer font table 
for printing characters encoded according 
to a code page based on ASCII. The system 
does not have a default file name. 


Incorrect, partial, or mismatched set up of commands tor code 

page selections, country code, keyboard layout, display, and 

printer may cause ineffective switching between cude pages at 

rum time. See the User Reference for the description and 

syntax of each command and the CHCP change code page command. 
Also see DosSetProcCp. 2.1.6.1.3 
2.1.6.1.2 DosSetProcCp - Set Process Code Page: Purpose 


Purpose DosSetProcCp allows a process to set its code page. 
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860 Portugese code page 
* 863 Canadian-French code page 
" 865 Nordic code page 


Reserved is a reserved word and must be set to zero. 
Returns If AX «<0 
NO error 
ELSE 
AX = Error Code: 


* Invalid code page 
® Invalid parameter value 


DosSetProcCp sets the process code page of the calling process. 
The code page of a process is used in the following ways. First, 
the printer code page is set to the process code page through the 
file system and printer spooler (the system spooler must be 
installed) when the process makes an open printer request. 
Calling DosSetProcCp does not affect the code page of a printer 
opened prior to the call and does not affect the code page of a 
printer opened by another process. Second, country dependent 
information will, by default, be retrieved encoded in the code 
page of the calling process. And third, a newly created process 
inhecits its process code page from its parent process. 
DosSetProcCp does not affect the display or keyboard code page. 


Also see DosSetCp. 


DosGetCp - Get Process Code Page: 


Allows a process to query its current process code page and the 
prepared system code pages. 


Format Calling Sequence: 
Format Calling Sequence: ; 
EXTRN DosGetCp:FAR : 
EXTRN Dosset ProcCp:FAR ; 
PUSH WORD Length i Length of list 
PUSH WORD CodePage ; Code page identifier PUSH@ OTHER CodePayeList ; Address of return data list 
PUSH WOKD Reserved ; Reserved PUSH@ WORD DataLength + Address of return data length 
Call DosSetProcCp ; Call DosGetCp ; 
Whece CodePage is a code page identifier word that has one of Where Length is the byte length of CodePageList. 
the following values: 
CodePageList is the return data list where the tirst 
« 437 8M PC US 437 code page word is the current code page identifier 
* B50 Multilingual! code paye of the calling process. 1f one or two code pages have 
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been prepared for the system then the second word is the 

first prepared code page and the third word is the 

second prepared code page. If the data length is less 

than the bytes needed to return all the prepared system 

code pages than the returned list is truncated. 

DataLength is the langth of the data returned in bytes. 
Returns If AX «< 0 

NO error 
ELSE 


AX = Error Code: 


Return data is truncated 
* Address error and data not moved 


Remarks 
The process code page identifier previously set by DosSetCp or 
inherited by the process is returned to the caller. An input list 
size of two bytes returns only the current process code page 
identifier. If no codepayes have been prepared with the CODEPAGE 
command, a length of two and current codepage identifier value of 
zero is returned. 

The system code page identifiers are returned to the caller in the 

same order as they appear tn the CODEPAGE command. The code page 

identifiers ace returned in the order: 

1. The current code page of the process (one of the system code 
pages). 

2. The primary (default) system code page. 

3. The secondary system code page, if specified. 

2.].6.1.4 DosGetCtryInfo - Get Country Information: 

Purpose Obtains country dependent formatting information that resides in 
the country tile (default name COUNTRY.SYS}. The country 
information returned currespunds tu the system country code or 
selected country code and the process code page of selected code 
page. 

Format Calling Sequence: 

EXTRN DosGetCtryInto:FAR 
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PUSH WORD Length sLength of data buffer 

PUSHE OTHER Stxucture sAddress of data structure 
PUSH@ OTHER MemoryBuffer ;Address of return data 

PUSH@ WORD DataLength ;Address of return data length 
CALL DosGetCtryInfo 


Where: 


Length is the byte length of the data area 
(MemoryBuffer) provided by the caller. A length value ol 
38 bytes is sufficient. In future releases of OS/2 the 
length required may increase. 


Structure is a two word input data structure: 
* Word 0: Country Code 
e Word 1: Code Page ID 


Word zero is the binary value of the selected country 
code where O means return the country information for 
the default system country code. Word one is the binary 
value of the selected code page identifier where 0 means 
return the country information for the current process 
code page of the caller. 


e 


MemoryBuf fer is the data area where the country 
dependent information will be placed. This memory area 
is provided by the caller. The size of the area is 
provided by the input parameter Length. If it is tou 
small to hold all the available information then as much 
information as possible is provided in the available 
space (in the order in which the data would appear). It 
the amount of data returned is not enough to fil) the 
memory area provided by the caller then the memory that 
is unaltered by the available data is zeroed out. The 
format of the information returned itn this buffer is: 


1 Word Country Code. 

1 Word Reserved (set to zero). 

1 Word Date format: Oumm/dd/yy, 1=dd/mm/yy, 
2@yy/mn/dd. 

Byte Currency indicator, null terminated. 

Byte Thousands separator, null terminated. 

Byte Decimal separator, nul) terminated. 

Byte Date separator, null terminated. 

Byte Time separator, null terminated. 

Byte Bit fieid for currency format: 


m AD AS AS AS LF 


Bit 0: l<currency indicator follows money 
value, 
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Oscurrency indicator precedes money 
value. 


Bat i: Number of spaces (0 or 1) between 
currency indicator and money value. 
Bat 2: When this bit is set, Ignore first 


two bits; Currency 
replaces decimat indicator. 


indicator 


1. Byte Binary number of decimal places used in 
currency indicat ion. 

} Byte Time format for tile directory presentation: 
Bit O: 1224 hour 
0-12 hour with "a" or "p". 

2 Word Reserved (set to zero). 

2 Byte Data list separator, nul! terminated. 

5 Word Reserved (set to zero) 


DataLength is the length in bytes of the country data 
returned. 


Returns If AX « 0 
NO error 
ELSE 
AX = Error Code; 
Country information fille open failed 
Country code not found in file 
Code pege identifier not found in file 


Information type not found in flle 
Buffer too small and information truncated 


Remarks None. 

2.1.6.1.5 DosCaseMap - Get Case Mapping: 

Purpose Performs case mapping on a string of binary values which represent 
ASCII characters. The case map in the country file (default name 
COUNTRY.SYS) that corresponds to the system country code or 
selected country code and the process code page or selected code 
Page is used to perform the case mapping. 

Format Calling Sequence: 

EXTRN DuosCaseMap:FAK 
PUSH WORD Length zLength of String to case map 
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PUSH®@ OTHER Structure zAddress of data structure 
PUSH@ OTHER BinaryString ;Address of case map string 
CALL DosCaseMap 


Where: Length is the byte length of the string of binary values 


to be case mapped. 
Structure is a two word input data structure: 
. Word 0: Country Code 


® Word 1: Code Page ID 


Word zero is the binary value of the selected country 
code where 0 means use the case map table for the 
default system country code. Word one is the binary 
value of the selected code page identifier where 0 means 
use the case map table for the current process code page 
of the caller. 


BinaryString is the string of binary characters that are 
to be case mapped. They are case mapped in place and 
replace the input so the results appear in BinaryString. 


Returns: IF AX = Q 
NO error 
ELSE 
AX = Error Code: 
Country information file open failed 
Country code not found in file 


Code page identifier not found in file 
Information type not found in file 


Remarks None. 

2.1.6.1.6 DosGetDBCSEv - Get DBCS Environment: 

Purpose Obtains a DBCS environmental vector that resides in the country 
file (default name COUNTRY.SYS). The vector returned corresponds 
to the system country code or selected country code and the 
process code page or selected code page. 

Format : Calling Sequence: 

EXTRN DosGet DBCSEv:FAR 
2.0 Functional Characteristics 18 


00044 





cv OPE Sly 0 da 


Microsoft Cont \dential Microsoft Confidential 


OS/2 1.2 IFS Patent Documentation OS/2 1.2 IFS Patent Documentation 
PUSH WORD Length sLength of data buffer | 2 Byte Nth range definition 
PUSH@ OTHER Structure sAddress of data structure 
PUSH@ OTHER MemoryBufter ;Address of return data Byte 1 binary start value for Nth range 
CALL DosGet DBCSEv Byte 2 binary stop value for Nth range 
Where: Length is the byte length of the data area 2 Byte Two bytes of binary zero terminate list 

(MemoryBuffec) provided by the caller. A length value of 

10 bytes is sufficient. In future releases of OS/2 the For example: DB 81H, 9FH 

length may increase. The caller can always determine if DB EOH,FCH 

alt the information has been obtained because it OB 0,6 

terminates with two bytes of zeros. A length of 2 wilt 

be sufficient fur information returned from non-DBCS Returns: IF AX = 6 

related countries. 

NO error 
Structure 1s 4a two word input data structure: 
ELSE 


* Word O: Country Code 

AX = Ercor Code: 
‘ Word 1: Code Page ID 
Buffer too small, information truncated 
Country information file open failed 
Country code not found in file 
Code page identitier not found in file 
Information type not found in file 


Word zero is the binary value of the selected country 
code where 0 means return the DBCS Information for the 
default system country code. Word one is the binary 
value of the selected code paye identifier where 0 means 
return the DBCS information for the current process code 
page of the caller. Remarks None. 


Memor yBuf fer is the data area whece the country 

dependent information for the DBCS environmental vector{ 2.1.6.1.7 DosGetCollate - Get Collating Sequence: 

is returned. This memory area is provided by the 

caller. The stze of the area is provided by the input Purpose Obtains a collating sequence table (for characters 00H through 


parameter Length. If it is tao small to hold all the FFH) that resides in the country file tdefault name COUNTRY.SYS). 
available information then as much information as It is used by the SORT utility to sort text according to the 
posstble is provided in the available space {in the collating sequence. The collating tabie returned corresponds to 
order in which the data would appear). Assuming the data the system country code or selected country code and the process 
area is lacge enough, the valid information is code page or selected code page. 
terminated by two bytes of 0. The format of the 
information returned in this bufter is: Format: Calling Sequence: 
2 Hylte Firest range definition for DBCS lead byte EXTRN DosGetCollate:FAR 
values 
PUSH WORD Length zLength of data buffer 

Byte 1 binary start value (inclusive) for PUSH@ OTHER Structure sAddress of data structure 

range one PUSH@ OTHER MemorcyBuffer ;Address of return data 

Byte 2 binary stop value finchusive) for PUSH@ WORD DataLength sAddress of return data length 

fanyjye one CALL DosGetCollate 
2 Yyte Second tanyge definitron Where Lenyth is the byte length of the data area 

(MemoryBufter} provided by the caller. A length value of 
Byte } binary start value for range two 256 bytes is sufficient. In future releases of OS/2 the 
Byte 2 binary stop value for range two length may increase. 
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Structure is a two word input data structure: 
. Word 0: Country Code 
a Word 1: Code Page ID 


Word zero is the binary value of the selected country 
code where 0 means return the collate table for the 
default system country code. Word one is the binary 
value of the selected code paye identifier where 0 neans 
return the collate table for the current process code 
page of the caller. 


MemoryHuffec is the data area where the collating 
sequence table is returned. This memory area is provided 
by the caller. The size of the area is provided by the 
input parameter Length. If it is too small to hold aj) 
the available information then as much information as 
possible is provided in the available space (in the 
order in which the data would appear). If the amount of 
data returned is not enough to fill the memory area 
provided by the caller then the memory that Is unaltered 
by the avallable data is zeroed out. The format of the 
information returned in this buffer is: 


1 Byte Sort weight of ASCH! (0) 

1 Byte Sort weight of ASCII (1) 
Hot {additional values in collating order) 
1 Byte Sort weight of ASCII! (255) 


DataLength is che length in bytes of the collate table 
returned. 


Returns: IF AX - O 
NO error 
ELSE 
AX = Error Code: 
Country information file open failed 
Country code not found tin file 
Code page identifier not found in file 


Information type not found in tile 
Buifer tow small and informatton truncated 


Remarks None. 
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2.1.7 System Initialization and Configuration 
The purpose of system initialization is to establish che environment = in 


which OS/2 (TM) executes. However, options exist in the system environment 
that the user may choose to configure. 


2.1.7.1 System Initialization 

System initialization ts done either as a result of a power on or by a 
System reset. System initialization is accomplished by the follawing: 

1. The Boot Sector 

2. OS/2 (TM) Device Interface Module initialization routine 

3. OS/2 (TM) Kernel Module initialization routine 


4. OS/2 (TM) System Initialization Process 


2.1.7.1.1 The Boot Sector: 


For diskettes, the boot sector begins on track 0, sector 1, side 0. For 


fixed disks, the boot sector begins on the first sector of the OS/2 (TM) 
partition. 


At a power on or system reset, ROM BIOS is invoked and performs hardware 
checks and initialization. Then ROM BIOS examines drive A for the boot 
sector. If the boot sector is not found, ROM BIOS chen looks in the active 
partition of the fixed disk. If no boot sector is found, then ROM BIOS 
invokes ROM BASIC. However, if a boot sector is located, ROM BIOS reads it 
into low memory and gives it contro}. 


When the Boot code gains control, the mode of operation is Real Mode. 


The Boot code loads the OS/2 (TM) Device Intecface Module into tow memory 
and gives it control. 


2.1.7.1.2 OS/2 (TM) Device Interface Module: 
The OS/2 (TM) Device Interface Module invokes its initialization routine. 


This initialization routine performs an equipment check and loads the 0S/2 
(TM) Kernel Module. It then invokes the OS/2 (TM) Kernel Module. 
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2.1.7.1.3 OS/2 (TM) Kernel] Module: 


The OS/2 (TM) Kernel Module Invokes {ts initialization code. This 
initialization code relocates the code for the System Initialization Process 
into high conventional memory (640 Kb or less). It also relocates kernel 
code and data segments in the appropriate places in memory. It initializes 
kernel components as well as the default device drivers. The scheduler is 
initialized with the System [DLE Process and the System Initialization 
Process. The mode of operation is set for protect mode and the System 
Initialization Process is invoked. 


2.2.7.1.4 OS/2 (TM) System Initialization Process: 


The System Initialization Process handles the contigquration commands in the 
CONFIG.SYS file, establishing the final operating environment. 


2.1.7.2 System Configuration ( CONFIG.SYS } 


CONFIG.SYS is the file that contains commands used to configure the system. 
Only a single CONF1G.SYS file is needed to configure the system for both 
reali mode and protect mode operations. 


Configuration commands and parameters will conform to the guidelines for 
country dependent information and messages as discussed in %------ ----- 
Saas Sas Seo " on page ---. 

During system initializaion, OS/2 (TM) opens and reads the CONFIG.SYS file 
in the root directory of the drive from which it was started and interprets 
the commands within the file. 

If a keyword specification 1!s invalid it is ‘ignored and the System 


Initialization default value is used. Reference each config.sys command for 
the default values. If a keyword is specified multiple Cimes, the last 
valid specification is used except for the tollowing keywords which may be 
specitied multiple times: 


. DEVICE 


component places several files in 1 or more 
directories generating the appropriate config.sys commands, thus making the 
CONFIG.SYS fille a required tile to successtully execute OS/2 (TM). 
Reference the System Install component for the list of commands required for 
the CONFIG.SYS file. 


NOTE: The System Install 


The following }ist summarizes the configyraton commands for O5/2 (TH). 


AUTOFAIL Disable/Enable system wide hard error and exception popup. 
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Determine the number of buffers to allocate for disk 1/0. 
Select the format for country-dependent information. 


Specify path and filename of a device driver to be installed. 


2.1.7.3 OS/2 (TM) Configuration Command Descriptions 


2.1.7.3.1 AUTOFAIL: 
Purpose Disable/Enable system wide hard error and exception popup. 
Format AUTOFAIL = yes | no 
where yes means that hard error and exception popups will not 
occur. Whenever such condition is encountered, = an 
appropriate error code will be return instead. 
mo means that hard error and exception conditions wit! 
Cause a popup to occur. 
Remarks The default is NO so the system will display the popup menu when a 
hard error or exception condition occurs. 
2.1.7.3.2 BUFFERS: 
Purpose Determines the number of buffers used for caching disk I/O that 
OS/2 (7M) will allacate. 
Format BUFFERS = x 
where x is a number betweer 1 and 100. 
Remarks The default value is 3. 
The disk buffer is a block of memory that a file system may use to 
hold data being read from or written to a disk. Sefore the file 
system reads or writes a record, it checks to see if that record 
is contained in a sector already ina buffer. If so, then the 
file system does not need to access the disk. 
The resident size of OS/2 (TM) increases by 512 bytes for each 
additional buffer specified. 
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2.3.7.3.3 COUNTRY: 


Purpose 


Format 


Hemarks 


2.1.7.3.4 


Purpose 


Format 


Rematks 


Selects the format for the country-dependent intormation. 

od Date and Time format 

e Currency symbol 

* Decimal: separator 

COUNTRY = nnon[, [d:] {path} fi lename.ext | 

where mon is the 3-digit international country code’ for the 
telephone system. Helfer to “------ ----2  -ne-- 0 on eee 
-----“ of page --- tor details and the list of supported 
countries. 

The default value 1s the U.S. country code of 00). 

If filename is not specified, the country information is supplied 

by the default COUNTRY.SYS file in the root directory on the 

system reset volume. 

If a filename is specified, the default drive/path is the system 

root directory if the drive/path is not specified. 


DEVICE: 


Specifies the path and filename of a device driver in order that 
{t may be installed. 


DEVICE = [d:) [path] tilename |.ext]) farguments] 
where d: is the drive and is optional 

path is optional 

filename.ext is required 


arguments are dependent on the device driver 


The standard default device drivers loaded by OS/2 (TM) support 
the console, printer, diskette, fixed disk, and clock 


devices. These device drivers do nut require any DEVICE* entries 
any CONF IG.SYS. 


To install other device drivers, the DEVICE= entry is required. 
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Both old and new device drivers may be loaded with the DEVICE- 


command. New OS/2 (1M) device drivers are initialized in protect 


mode; old device drivers are initialized in real mode. 


DEVICE= commands are processed in the order in which they appea:z 


in CONFIG.SYS. 


No DEVICE= commands (for model group dependent device 


drivers) 


will be allowed ln CONFIG.SYS to support basic OS/2 operation. 1 


a default CONFIG.SYS is shipped with OS/2 then it will contain nu 
drivers that are model 


DEVICE= commands for device 
dependent. Any device drivers required for OS/2 basic 


will be loaded in automatically from hidden and reserved 
names. The filenames used will depend on the model group that the 


IPL is occurring on. 


The correct DEVICE- parameters are determined by INSTALL or the 


user as discussed above. 


2.1.68 Installable File System 


2.1.8.1 Requirements on The IFS Mechanism 


The Installable File System (IFS) Mechanism supports the following: 
* Coexistance of active file systems in a single PC, 

- Multiple logical volumes (partitions), 

* Multiple and different storage devices, 

Redirection or connection to remote file systems, 


a File system flexibility in managing its data and I1/O for 
perfocmance, 


Transparency at both the user and application level. 
® Standard set of Flle 1/0 API, 
Existing logical file and directory structure, 


. Existing naming conventions, 
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* File system doing its own buffer management, 

* File system doing file 1/0 without intermediate buffering, 
s Extensions to the Standard File 1/0 API (File System CTL), 
e Extensions to the existing naming conventions, 


. IOCTL type of communication between a file system and a device driver. 


2.1.8.2 Description 


2.1.8.2.1 System Relationships: 


The LFS Mechanism defines the relationships among the operating system, the 
tile systems, and the device drivers. The basic model of the system is 


represented in Figure 4 on page 88. 


2.0 Functional Characteristics 


87 


Microsoft Confidential 
OS/2 1.2 IFS Patent Documentation 


| 

i 

t 

4 

4-------- + to------- + S Restededusated -~-¢ | j 

|) file 1 | file | | file t t I 

| system | | system | {| system | 1 i 

| 1 \ 1 1 t ot 1 

{ LOCAL {} | NET i | NET $ | I 

| i | REDIRI | | REDIR2 1 } f 
Se | teaneen-- + Pore eene- + 4 j 

Br ee eee em nee me ee ee men men nee e t ] 
( | 
1 FS Helpec Routines / t 
4 Device Driver Request Router H 
| | 
Pen nr rn nnn een enn ne ee mene nn + | 
ten e--—e + t{oeee---- Ft  teeeeren=- + j { 

f l j i of t ( I 

{ device | { device | { device | { j 

{ driver | | driver {| § driver | l i 

{ J 5 ; 3 l I ! 
teresennn— + SR tented $ teow ----4 { 

Br rn tn eee meen men nm me eee mm t j 
j i 
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Figure 4. System Relationships for Installable File Systems 


The Request Router directs File 1/0 system calls to the appropriate file 
system for processing. 


The file systems manage file 1/0 and control the format of information on 
the storage media. An installable file system will be referred to as a file 
system driver or FSD. 


The FS Helper Routines provide a variety of services to the file systems. 


The device drivers manage physical I/O with devices. Device drivers do not 
understand the format of information on the media. 
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2.1.8.2.2 Standard File 1/0: 2.1.4.2.3 Extended File 1/0: 


Standard file 1/0 is performed through the Standard File 1/0 AP1l. The user New API may be provided by a file system to implement functions specific to 

makes a system call, and the Request Router passes the request to the the file system or not supplied through the standard file I/O interface. 

correct file system tor processing. Any new AP] would be provided as a dynamic link package that would use the 
DOSFSCTL to communicate with the specific file system. 


user user 
| ! 
Vv Vv 
tee tem nm ene nn erm nnnee t Dynamic tomer mene meme enn enn + Dynamic Link 
| Standacd File 1/0 API |) Link | Extended File 1/0 API | Library 
forever nse wen we mmo men nen ¢ Library $e sees eee SSH sss een ES t 
! for S seeeieele eas 
eee eee ee eee Vn we ene enn ee en eee ¢ File System v ; 
i | DOS/C foe recare rs Seem enn en + Standard 
] Request Router j 1 PDosFSCt 1 1! File {/0 
' | esr ae Keema sem mae 4 API 
Am MORN Me 8 RRO ROR Kwa eR maw nee owen wees + | : 
l | Tee SSS e Ss eee Se an a a Rn ee ated eet 
to--en ene 1 ¢-----+-~ ¢ teenneene t | \ \ opeceee 
1 file j | file I i file i ol i | : { 
| system | } system | | system |} \ {rst ease ses=e4= Gere ote Seen ae i 
trove ceen SE, Sehetetetetetedes t tere eenn- 4 | j Vv 1 j 
{ { teen n-~- + tenn---~- + tea------ + | t 
tae ne er nn ne nn ne een nnn e nn --- 4 i | tile | i file | i file | | i 
| { | system | | system | | system | | { 
Peer cree mmo werner enna mene terri ter— aes + t tosccere= + t DOS/C | teow wren + 4 4 
toon e een + temnce ne to tenner een + t | teooee oo=+ ] { 
{ device | | device |} | device | { | ' i 
i driver j | deiver | | driver | | | a aa aaa aa ad ‘ { 
tearn---- 5 teoe----- oe 4 i i { ; 
$n en oe een ¢ ( tenn —wee oe ee em + } 
, | tewn----~ + Henne ene i re + | | 
i device | | device | {| device | I | 
(ist eee Re eo ue ee wes ees cee ae eR sie ne seen eee elas + | driver } | driver { | driver | i | 
toowecoen + tewene--- 5 EE Deleted | | H 
town mene mmeenn A ee ee am er em rn -+t | 
Figure 5. Standard tile 1/0 J 
Peete n nn wm nen nnn ee en ee ee + 
Figure 6. Extended File 1/0 
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2.1.8.2.4 1/0: 


There are two general classes of tile 1/0 that must be taken into account by 
the IFS Mechanism. The two general classes of file 1/0 are synchronous 1/0 
and asynchronous 1/0. 


In the case of synchronous file 1/0, a task issues a system ca}] for 1/0 and 
will not regain control until the operation has been performed. The flow 
through the mode} of system relationships is represented in Fiqure 7 on page 
92. : 
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DOSREAD ~~ ene e = + 
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TASK 1 f 
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J REQUEST 1 | 
| ROUTER READ 
t 1 | 
tonne nnn enn ne ene ene ee A OV ----- + 
FILE t | ! 
SYSTEM town ern we en nn + j 
| I/O CALL | 
[ i { 
teewnnn nnn enn A wwe ene eren nee = Vo ----- 4 
| FS | ie 
| HELPERS } build RB 
\ b | 
wekl call Strategy 
I : ProcBiock RB j 
! : \ i 
Pore eee n eee A ocewreene A omme-ne Voww--~ + 
DEVICE : ' i { 
DRIVER Seceacen j ] | 
> Vv | 
to ecocnoe- + : | : Koctesintesteatedoateneenten + | 
HW <-<-------- >linterrupt! =: | | Strategy [{ | 
INT | Service | =: | tee enn me + | 
teacaa=<=- t+ 3 | 
: 20 teeecene en + } 
: : ; 
aos sessed Yeoeseee SSS SSeesseSs= t 
} DEVICE : 2 
{| DRIVER ProcRun RB : 
i HELPERS Svevéeeuas 


Figure 7. Synchronous 1/0 Example 


In the case of asynchronous file 1/0, a task issues 
and regains control before the 1/0 has been performed. 
model of system relationships is represented in Figure 
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8 on page 93. 
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hiding the real nature of a task‘s request from the file system is to retain 
control in the kernel. This gives the kernel the freedom to later optimize 
DOSREADASYNC {Ram Sem) ---+¢ the handling of asynchronous 1/0. 


* 2.1.8.2.5 Buffer Management : 


The 1fS mechanism allows an FSD to do its own buffer management. 


} REQUEST | { CreateThread 
| ROUTER DusSemRequest t | { 
! (Ram Sem) t----4 | 


The FSD moves all data, requiring partial sector I/O, between the 
application’s buffers and its cache buffers. The FS helper routines 
initiate the 1/0 for local file systems. 


TerminateThread dane tt 
| 

DosSemC lear 

{Ram Sem) 


An FSD may use the OS|2-managed buffer cache using FS helpers. 


An FSD may do ail buffering entirely on its. own. 


2.1.8.2.6 Volume Management ; 


Volume management, i.e., detecting when the wrong volume is mounted and 
notifying the operator to take corrective action, is handled directly 
through OS|2 and the device driver. Each FSD is responsible for generat ing 
a volume label and 32-bit volume serial number. It is strongly suggested 
that these be stored in a reserved location in logical sector zero at format 
Lime. 


FILE 1 
SYSTEM tao meen nnn anne rt 


ij €S 
build RB 
a | 


1 
\ It is not required that an FSD use a particular format to store this 
t 
aoe call Strategy 
P 


information. OS(2 will call the FSD to perform operations § that might 
involve it. The FSD is required to update the VPB whenever the volume labe! 
Oc serial number is changed. 


When the FSD passes an I/O request to an FS helper routine the driver passes 
the 32-bit volume serial number and the user's volume label (via the VPA). 
When the I/O is performed, OS|2 compares the requested volume serial number 
with the current volume serial number it maintains for the device. This is 
an in-astorage test (no 1/0 required) performed by checking the Drive 
Parameter Block’s {DPB) VPB of volume mounted in the drive. If unequal, 
OS|2 signals the critical error handler to prompt the user to insert the 
volume having the serlal number and label specified. 


DRIVER 


HW ---------- >pInterrupe| 
INT 1 Service | 


tee mene ne mee Vo me eee peer e ee nee meen eene 4 
i DEVICE $ $ 
| DRIVER ProckKkun HB ; 
| HELPERS og bet euue ae 


When OS|2 detects a media change in a drive, or the ficst time a drive is 
accessed on behalf of an API function call, it will determine che FSD (file 
system driver) that will be responsible for managing 1/0 to that volume. 
OS{2 will allocate a VPB {volume parameter block) and poll the installed 
FSDa (by calling the FS_MOUNT entry point) until an FSD indicates that it 
does recognize the media. . 


Figure 8. Asynchronous 1/0 Example * The FAT FSD will be the last in the ist of FSDs and, by recognizing all 


media, will act as the default FSD when no other FSD recognition takes 
As can be seen by the examples, che file system does nat have special{ place. 
knowledge of the nature of the task’s original request. One reason for 
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2.1.8.2.7 Connectivity: 
There are two classes of tlle system drivers: 


* an FSD which uses a block device driver to do 1/0 to a local or remote 
(virtual disk) device. This is called a local file system, 

* an FSP which accesses a remote system without a block device driver 

This is called a remote file system. 


The connection between a drive letter and a remote file 
through a command interface. 


system is achieved 


The connection between a pseudo-character device and a local or remote file 
System is achieved through a command interface. ' 
when a local volume is 
the FSD chain to accept the media, via call to each FSD’s FS _ MOUNT entry 
point. If no FSD accepts the media then it is assigned to the default FAT 
file system. Any further attempt made to access an unrecognized media other 
than by FORMAT, will result in an ’Invalid media format’ message. 


Once a volume has been recognized, the relationship between drive, FSD, 
volume serial number, and volume label is remembered. The volume serial 
Mumber and label! are stored in the Volume Parameter Block, (VPB). The VPB is 
maintained by OSI2 for open files (file-handle based 1/0), searches, and 
buffer references. The VPB represents Che media. 


Subsequent requests for a removed volume require polling the installed FSDs 
for volume recognition by calling FS_MOUNT. The volume serial number and 
volume label of the VPB returned by the recognizing FSD and the existing VPB 
are compared. If the test succeeds, the FSD is given access to the volume. 
lf the test fails, OS{2 signals the critical error handler to prompt the 
usec for the correct volume. 


The cannection between media and VPB 1s cemembered until all open files = on 
the volume are closed, search references and cache buffer references are 
removed. Only volume changes cause a re-determinatian of the media at the 
time of next access. 


2.1.8.2.8 IPL Mechanism: 


A primary DOS disk partition (type 1, 4, or 6) may be used to boot the 
system. The code for FSDs may reside in any partition readable by a 
previously installed FSD. An IFS partition must be a type 6. 


includes the following: Boot record, basic file 
files, OSi2 initialization files, Advanced 
and base device drivers. Boot partitions 


The OS|2 boot partition 
system structure, BIOS and DUS 
10S patch files, CONFIG.SYS, 
always contain FAT file systems. 
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1f the media isn’t bootable, there need not be a FAT partition present. 


Device drivers and FSDs are loaded in the order they appear, and are 
considered elements of the same ordered set. Thus both device drivers and 
FSOs may be loaded from installed fille systems, so long as they are started 
in the proper order. For example: 


DEVICE = c:\devices\diskdriv.sys 
REM Block device D: is now defined. 
IFS = c:\fsd\newfs1. fad 

REM If we assume that D: contains a fixed newfsl type partition, 
REM then we're now ready to use D: to load the device driver and 
REM FSD for £E:. 

DEVICE = d:\root\dev\special .dev 

REM Block device Es: is now defined. 

IFS = d:\rcoot\fsd\special.fsd 

REM E: can now be read. : 

DEVICE = e:\music 


(diskdriv.sys controls this.) 


2.1.8.2.9 OSJ2 Partition Access: 


Access to the OS|2 partition on a bootable, logically partitioned media is 
through the full OS{2 function set. A detailed description of the disk 
Partitioning design is available in the OS|2 1.1 FPFS. 


2.1.8.2.10 Permissions: 


An architecture for secure file systems has been considered but not 
formalized. There are no secure file system clients identified for the 
first release of OS}2 incorporating the IFS architecture. 


2.1.8.2.11 File Naming Conventions: 


OS/2 1.2 will view ‘path names’ as ASCIYZ strings and not restrict FSDs to 
the DOS file name format: xxxxxxxx[.yyy) (8.3 format). This allows an FSD to 
use whatever naming convention is appropriate for it today and to extend 
DOSQSYSINFO should 


" be called at initialization time to determine maximum path length. 


Applications that can support non-8.3 format filenames must set the 
LONGNAMES blt in theic executable header in order to be able to manipulate 
auch names. 


After the OS/2 name processing has completed, the path is passed to the FSD 
using the FS_PROCESSNAME interface for enforcement. of FSD-specific naming 


conventions. 
*"\' and °/"’ are not valid file name characters. Names in paths are 
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delimited by ‘\’ or ‘/’ and have no drive letters. This supports other 
Operating System name formats {e.g., VM, UNIX, RPS, EDX). 


The file names ‘.’ and ‘..’ ace ceserved for use by hierarchical directory 
structures for the current directory and the parent of the current directory 
respectively. The names ‘.' and ‘..‘ receive special processing during 
Canonicalization, and will never be seen by any FSD. 


The '.’ and ’..* notation must be used by file systems using hierarchical 
directory structures, with the semantics described above. In additton, ’.* 
and ‘..’ must be physically present in all directories. 


File system drivers which support hiecarchical directory structures must use 
"\' and ‘/* as path name component separators. '"\' and '/* are identical in 
meaning. No other character may be accepted as a path separator. File 
system drivers which do not support hierarchical directory structures must 
reject as illegal any use of ‘\" of ‘/* in path names. 


If an FSD uses a component separator within a filename, it must be ‘.*. 


There are no restrictions on the number of components which may be allowed]* 


within a flle name. 
FSD filenames ace restricted to the OS|2 character set. 


All filenames are case insensitive (that is, all lower case alphabetic 
characters are automatically converted to the equivalent upper case 
chacacters). This applies to all system canonicalized file names. The 
filenames passed to an FSD will be converted to uppercase but the 
filenames/data that may be passed in data buffers to an FSD will not be 
processed this way. 


The invalid characters for filenames are the range 0-1Fh and the characters 
cae. aj", e\e, ial fad “j°, sah a ee, sed Haat a>" myn, 1%», & woe and o,*. This 


list applies to labels and EA names also. 


For compatibility reasons, the OS!2 FAT file system will continue to only 
Support the old DOS file name format: xxxxxxxxf.yyy) (8-5 format). It is 
required that OS|2 and PC/DOS media be compatible within the FAT File System 
context. 


Compatibility with existing DOS 3 applications requires all FSDs to support 
a superset of the FAT file system’s 8.3 turmat. 


IFS requests issued from the 3x box wil! have the 9.3 truncation rules 
applied before the FSD receives the request. FSOs do not need to know if a 
particular request is issued by the 3x box. 


Applications are not expected to understand FSD-specific naming conventions. 
Parsing of names is to only take into account "\‘, °/’, °.°, and ’..’. 


For compatibility reasons, tratling dots on component names are discarded. 
For example, “\loo.bar...bletch...\a..b...\c." becomes 
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“\foo.bar...bletch\a..b\c". This processing includes semaphore, queue, 
pipe, module, shared memory names, and device names. 


2.1.8.2.12 Meta Character Processing: 


Meta characters will work in the following way for all programs regardless 
of level number. Meta characters are illegal in al} but the last component 
of a path. 

¢ 
Meta characters have two sets of semantics. The first is as search 
characters, where they are used to select which filenames are returned tv 
the user. The second is as edit characters, used to construct a new name 
given a source name and a Larget name specification. The second use occurs 
in places like “copy *.txt *.old", and is ngt actually supported anywhere in 
the kernel except in FCB_rename, and some special FCB editing calls. 


Thus, both “*" and 2" have two rules, one for searching, one for 
copy-editing used in “ren <name-with-metas> <name-with-metas>*, and such. 


“." has no special meaning itself in searching, but ? gives it one. 


“." has a special meaning for eaditing. 
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|} 2.1.8.2.14 FS Ucility Support: 
* Searching 
i Each FSD is required to provide a single .DLL executable module in order to 
" matches 0 or more characters, any character, including blank. {| support the OS|2 FORMAT, CHKODSK, SYS, and RECOVER utilities. The FS-provided 
e It will not cross NUL or \. (Which means it only matches a filename, | executable will be invoked by these utilities when performing a FORMAT, 
® not an entire path.) | CHKDSK, SYS, or RECOVER function for that file system. The command line 
{ arguments and environment pointer that was passed to the utility will be 
| ? matches 1] character, unless what it would match {is a‘. or the | passed unchanged to the FS-specific executable. 
i terminating NULL, in which case it matches 0 characters. (It also 
{ doesn’t cross \.) The procedures will reside in the file called U<fsdname>.DLL, where 


| 
| <fsdname> is the name returned by DosQFsAttach. 1f the file system wishes to 
| 
i 


: Any character other than ® and ? matches itself, including . be able to have its utility support .DLL file on a FAT partition, then it 
should choose <fsdname> co be up to 7? bytes long. 

* Editing 1 The FSD utility procedures are expected to follow the following rules: 
a metas if the source simply match files, and behave just like ' * No preparation will be done by the base utilities before they invoke the 
® any other search meta. (see above} b FSD utility procedure. Thus, the base utilities will not lock drives, 

i parse names, open drives, etc. This allows maximum flexibtlity for the 
« metas in the target are copy-edit commands, and work like this: | FSD author. 
® ? copies one character, unless what it would copy is a *.", | * The FSD utility procedures are expected to follow the standard 
. in which case it copies 0. It also copies 0 characters if { conventions for the operations that they are performing, e.g. /F for 
" we're at the end of the source string. ! CHKDSK implies "fix". 
| * copies charactecs from the source to the target until it finds | ¢ The FSD procedures may use stdin, stdout and stderr if they wish, but 
} a source character that matches the character following it in } should be aware that they may have been redirected to a file or device. 
I the target. 

it * It is the responsibility of the FSD procedures to worry about volumes 

. . in the target “syncs” pointers. It causes the source 1 being changed while the operation is in progress. The normal action 
. pointer to match the corresponding "." in the target. They \ would be to stop the operation when such a situation is detected. 
° count from the lett. 

!* When the FSD procedures are called, they will be passed argc, argv and 
e The DOSEDITNAME API performs the described operation. ! envp that they can use to determine the operations. 5 


; * The FSD procedures are responsibie for putting out the relevant prompts 
i and messages. 
¢ For compatibility resons, any file name that does not have a dot in it gets 
¢ an amplicit one automatically appended to the end during searching}i * The FSD utility procedures are expected to follow the standard 
t operations. This means that searching tor “foo.” would return “foo”. | convention of entering the target drive as specified for each utility. 


2.3.8.2.143 Family AP1 issues: 
| Interfaces for the FSD procedures 
Since the IFS mechanism 18 neithec present in previous releases of OS|2 nor 
present in real-mode DUS versions 2.0 through 3.3, FAPI will not be extendedj| Ali the FSD utility procedures are called with the same arguments as 
to support the new interfaces. | follows: 


{ * int far pascal Ufsdname.CHKDSK {int argc, char far * far *argqv, char far 
| * far *envp) 


|* int fac pascal Ufsdname .FORMAT(int argc, char far * far *argv, char far 
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* tar “envp) 


® int far pascal Ufsdname .RECOVER{int argc, chac far * far *argv, char far 
* far "envp) 


* int far pasca] Ufsdname.SYyS(int argc, chat far * tar *argy, chac far * 
far *envp) 


Where argc, argv and envp have the Same semantics as the corresponding 
variables in C. 


2.1.8.2.15 FSD Pseudo-Character Device Support: 


A pseudo-character device (single file device} may be redirected to an FSD. 
The behavior of this tile is very similar to the behavior of a normal DOS 
Character device. Jt may be read from (DosKkead) and written to (DosWrite). 
The ditterence is that che DosChgtilePlr and DuosFileLocks functions can also 
be applied to the tile. The user would perceive this file as a device name 
for a non-existing device. This file is seen as a chatacter device because 
the current drive and directory have no effect on the name. This is what 
happens in DOS today for characler devices. For example: 


FILESYS HOST BCRVMPC] USERID PASSWORD 


would define a tile (or device) through which host communication can be 
established. A TYPE HOST command would display the latest host created data 
and a COPY CON HOST command could be used to send commands to the host. 
This example assumes the FSD BCRYMPC] can perform the necessary host 
communication and translation. 


The format of an OS|2. pseudo-character device name (i.e., single file 
device) is that of an ASCIIZ string in the format of a OS|2 filename ina 
subdirectory called \DEV\. The pseudo device name HOST is accessible at the 
API level {DosQFsAttach) through the path name: ‘’\DEV\HOST’. 


2.1.8.3 Extended attributes 


kxtended attributes (EAS) are a mechanism whereby an application can attach 
informatitun to a file system object (ditectucies of files) describing the 
object to another application, to the opetating system, ofr tO the FSD 
managing that object. 


This data 15 not kept as pact of the object's data itself; to do this would 


tequire alt applications to understand the object’s focmat and would give 
the applications direct access to all] other EAs. Normally, applications 
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will deal with a subset of the EAs that may exist on an object. 


Each EA has two parts: a name anda value. The name is asciiz text that is 
used to identify a particular EA. There is no other mechanism to identify a 
particular EA. The name portion of EAs is chosen by the application 
programmer. This poses the problem of name collision. To address this, a 
naming convention is adopted. This convention is quite simple; the name is 
prefixed with the name of the company {or suitable abbreviation) and the 
name of the product (or suitable abbreviation) that defines the attribute. 


All kernel-defined EAs will be prefixed with *pOS.". 
EA mames are restricted to the same character set as filenames. 


The value portion of an EA may be arbitrary data or it may be ascii data. 
There are many different representations for the value portion of EAs. 
Rather than mandate a specific format, the following guidelines should be 
used: 


If a simplification/optimization can be achieved in the application by 
representing che value as binary data (such as icons or Cimestamps) then 
the cepresentation should be binary. 


Otherwise, the representation should be displayable tn all character 
sets (i.e. restricted to characters 0x20 through Ox7E). 


EAs may be viewed as a property list attached to objects. The services for 
manipulating EAs are: add/replace a series of name/value pairs, return 
name/value pairs given a list of names, and return the total set of EAs. 


There are two formats for EAs as passed to OSj2 vl.2 API: Full EAs (FEA) or 
Get EAs (GEA). 


FEAS are complete name/value pairs. In order to simplify and speed up 
scanning and processing of these names, they are represented as  length- 
preceded data. FEAs are defined as follows: 


struct FEA { 


unsigned char reserved; /* must be 0 af 
unsigned char cbName; /* length of name a/ 
unsigned short cbValue; /* length of vaiue a/ 
unsigned chart szName{); /* asciiz name al 
unsigned char aValue|j; /* free-format value */ 


Me 


The name length does not include the trailing NUL. The maximum EA nam 
length is 255 bytes. The minimum EA name length is 1 byte. The characters 
that form the name are legal filename characters. Wildcard characters are 
not allowed. EA names are case-insensitive and should be uppercased. The 
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¢ FSP should call FSH-CHECKEANAME and FSH_UPPERCASE for each EA name it 
+ receives to check for invalid characters and correct length, and to 
+ uppercase it. 


A list of FEAs is a packed set of FEA structures preceded by a length of the 
list (including the length Itself} as indicated in the following atructure: 


struct FEAList ¢. 
unsigned short cbhList; 
struct FEA \list]]; 
de 


/* length of list e/ 
/* packed set of FEA */ 


FEA lists ate used tor adding, deleting, of changing EAs. A particular FSD 
may store the EAS in whatever format {t desires. Certain EAs may be stored 
to optimize retrieval. 


A GEA is an atlribute name. Its format is: 


struct GRA { 
unsigned char cbName; /* length of name */ 
unsigned char szName{); /* asciiz name “7 


hs 
’ 


The name length does not include the trailing NUL. 


A list of GEAs is a packed set of GEA structures preceded by a length of the 
list (including the length itself) as Indicated in the following structure: 


Struct GEAlList | 
unsigned short cbList; /* length of jist af 
struct GEA list}; /* packed sect of GEA */ 
h? 


GEA tists are used for retrieving the values for a particular set of 
attributes. It is used as input only. 


Name lengths of 0 are illegal and are considered in error. A value length 
of 0 has special meaning. Setting an EA with value length of 0 will cause 
that attribute to be deleted (if possible). Upon retrieval, a value length 
of 0 andicates Chul the attribute 1s not present. 


Setting atlributes contained in an FEA list treats the entire FEA list as 
atomic: a] of the changes specified in the list are applied or none will. 
This 1s required since the attributes together may specify some behaviour 
for the file system and may not make sense being set independently. 
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The routing of RA requests is accomplished via the IFS routing mechanism. 
EA requests that apply to names are routed to the remote FSD attached to the 
specified drive or ta the local FSD managing the volume in the named drive. 
Those requests that apply to a handle (file or directory) are routed to the 
ESD attached to the handle. No interpretation of either FEA lists nor GEA 
lists is performed by the IFS router. It is the responsibility of each FSD 
to provide support for EAs. It is expected that some FSDs will be unable to 
store EAs (e.g. UNIX~ and MVS-compatible file systems} 


The FAT FSD implementation will provide for the complete implementation of 
EAs. There will be no specia) EAs for the FAT FSD. 


All EA manipulation is performed using the following structure; the 
relevance of each field is described within each API: 


struct EAOP { 
Struct GEAList far * FpGEAList; /* GEA set s/f 
Struct FEAList far * fpFEAList; /* FEA set "/ 
unsigned short offError; /* offset of FEA err */ 
hj 


In the OS2 V1.2 release, values of cbList greater than (64K-1) will not be 
allowed. This is an implementation defined limitation which may be raised 
in the future. Gecause this limit may change, programs shovld avoid 
ennumerating the list of ali EAs, but instead manipulate only BAs that they 
now about. For operations such as copying, the DosCopy api should be used. 
If enumeration is necessary, the DosEnumAttribute API should be used. 


A special category of attributes, called create-only attributes, is defined 
as the set of extended attributes that a file system may only allow to be 
set at creation time. (Such attributes may be used to control file 
allocation and structure configuration.) File systems are expected to allow 
create-only attributes to be set at any time >from when the object is 
created to when it is first modified, 1.e. data written into a file or an 
entry added to a directory. Programs that copy objects should copy all of 
the EAs for an object before otherwise modifying it in order to assure that 
any create-only attributes from the source are properly applied to the 
target. The DosCopy{) api is the prefered way for copying files o: 
directories. 


2.1.8.3.1 FSD File Image: 

An FSD loads from a file which is in the format of a standard OS}2 dynamic 
link library tile. Exactly one FSD resides tn each file. The FSD exports 
information to OSj2 using a set of predefined public names. 


The FSD is tnitialized by a call to the exported entry point FS_INIT. 


FS entry points for Mount, Read, Write, etc. are exported with known names 
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as Standard far entry points. 


The FSD exports its name as a public asciiz character string under the name 
‘FS NAME’. All comparisons with user specified strings will be done similar 
to file names; case is tignored and embedded spaces are significant. 
FS NAMEs, however, may be input to applications by users. Embedded spaces 
should be avoided. The name exported as FS NAME need NOT be the same as the 
1-8 byte FSD name in the boot sector of formatted media, although it may be. 
The ONLY name the kernel] pays any altention to whatsoever, and the only name 
accessable to user programs via the API 1s the name exported as FS NAME. 


In addition to various entry points, the FSD must export a dword bit vector 
of attributes. Attributes are exported under the name ‘FS ATTRIBUTE’. 
FS ATTRIBUTE specifies special properties of the FSD and is described in the 
mext section. 


2.1.8.3.2 FSD Attribute, FS_ATTRIBUTE: 
The tormat of the OS|2 FS_ATTRIBUTE field is defined below: 
OS|2 FSD ATTRIBUTE 


31 30 29 278 27? 26 25 24 23 22 21 #20 19 #18 17 16 
ed ee ee ee ee ee ee ee ee eee eee eee eee eee 
TAT AVATAVALATA LEEALALEAR LAMAR AERO TLE eee 
PAASVSES USES USES IAAL ALS LUST EN ELT ELLEN EAN TES 
WARAUA AULT AVA VATA REE AE CAE E ee EEA 


eee ete Rates Sete ree Seen So enes Sees Soraya ee ee ee eee eee eee ere 


15 14 #13 #12 «2121 «210 9 8 7 6 § 4 a. 2 1 0 
$ret tan Baa a tan tan Fe dn bn tenn tenn ge nn tenn tine te se tenn 4-4 
ELSA USTT STANSELL ALTA ETL FEN TELA ESV SOS LARS 
PASAASAIULELVA TENT ELE RTLINETAEEL LINEA AES 
ASL USTIVAL LRT TIN TLV TTL TENT LENT OF SCS MZ | 


Pee Seeman Serene Serene Serene Botetes Serene Seer ee ee ee ee eee eee eee 
BITS DESCRIPTION 
3] FSD Extended Attributes. If 1, FSD has extended attributes. If 


0, FS_ATTRIBUTE is only FSD attribute information. 


30-28 VERSION NUMBER - FSD version number. 

27-3 RESERVED. 

2 FIO ~ File 1/0 bit. Set if FSD wants to see file locking/unlocking 
operations and compacted file 1/0 operations. If not set, the 
fileio calls will be broken up into individual 
lock/unlock/read/write/seek calls andthe FSO will not see the 
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lock/unlock calls. FSDs that do support FS _FILEIO can set this 
bit to enable compacted file I/O operations. 


1 UNC - Universal Naming Convention bit. Set if FSD supports 
Universal Naming Convention. If set, then FSD represents § the 
default network redirector. Oniy one FSD may have this bit set. 


0 REM - remote file system. This bit telis the system whether the 
FSD uses static or dynamic media attachment. Local FSDs always 
use dynamic media attachment. Remote FSD’s always use static 
media attachment. This bit is Clear if it is a dynamic media 
attachment and Set if static attachment. No FSD supports both 
static and dynamic media attachment. To support proper file 
locking, a remote FSD should also set the FIO bit. 


2.1.8.4 FSD Initialization 


FSD initialization occurs at system initialization time. FSDs are loaded 
via the IFS = configuration command in CONFIG.SYS. Once the FSD has been 
loaded, the FSD’s initialization entry point is called to initialize it. 


FSDs are structured the same as dynamic link library modules. Once an FSD 
is loaded, the initialization routine FS INIT is called. This gives the 
FSD the ability to process any parameters that may appear on the CONFIG.SYS 
command line, which are passed as a parameter to the FS_INIT routine. A 
LIBINIT routine in an FSD will be ignored. 


OSi2 FSDs initialize in protect mode. Because of the special state of the 
system, an FSD may make dynamic link system calls at init-time. The list of 
system calls that an FSD may make are as follows: 


FSD INIT 

DYNAMIC LINK SYSTEM CALLS 
DosBeep 
DosChgFilePtr 
DosClose 
DosDe lete 
DosDevConfig 
DosDeviIocr hk 
DosFindC lose 
DosFindFirst 
Dos tndNext 
DosGetEnv 
DosGet InfoSeg 
DosGet Message 
DosOpen 
DosPutMe ssage 
DosQCurDir 
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DosQCurDisk 
DosQFileinto 
DosOF i JeMode 
DosQSysinfo 
DosRead 
DosWrite 


The FSD may not cal) FS helpers at initialization time. 


{t should be noted that multiple cade and data seqments are not discarded by 
the loader as in the case of device drivers. 


The FSD may call DosGetInfoSeg to obtain access to the globa)] and process 


* local information segments. The loca! segment may be used in the context of 


eC — —_— = 


ail processes without further effurt to make it accessible and has the same 
selector. The local infoseg 1s not valid In real mode or at interrupt time. 
2.1.8.4.1 OQSi2 and PC/DOS 3.4 Boot Record and BIOS Parameter Block: 

The extended Boot Record structure: 


Extended Boot struc 


Hoot jmp db 3 dup (?) 
Boot OEM db @ dup (7?) 
Boot BPB db (size Extended BPB) dup (?) 


Boot DriveNumber db 2 
Hoot CurrentHead db ? 


Hoot Sig db 4) sIndicate Extended Boot structure. 
Hoot Serial dd ? 

Boot Vol Label db 11 dup (7) 

Boot System 1D db 8 dup (?);"FAT *, “OTHER FS" 


Extended Boot ends 
Area for code and messages 
Boot Signature db 55h, OAAh 


Where Serlal is the 32-bit binary volume serial number for the media. 


System 1D is an &8-byte name written when the media is formatted. 
It is used by FSUs to identify thelr media, but need NOT be the 
Same as the name the FSD exports via FS_NAME, and is NOT the name 
users employ to refer to the FSD. {They may, however, be the same 
names.) 


Vol Label 1s the li-byte ASCII label of the disk/diskette volume. 
FAT filesystems must ALWAYS use the volume labe! in the root 


directory for compatibility reasons. A FSD may use the one in the 
Standard boot sector 1f 1t so desires, 


The extended BPB structure is a super-set of the conventional BPB structure. 
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Extended BPB struc 


BytePerSector dw 2? 

SectorsPerCluster db ? 7See the remark below 
ReservedSectors dw ? 

Numbe rOfPATs db ? 70 for Non Fat system 
RootEntries dw 2 7See the remark below 
TolalSectors dw 7? zif O then use Ext_TotalSectors 
MediaDescriptor db ? ¢See the remark below 
SectorsPerFat dw ? ¢See the remark below 
SectorsPerTrack dw ? 

Heads dw ? 

HiddenSectors dd 3 332 bit hidden sectors 
Ext_TotalSectors dd ? 332 bit total sectors 


Extended BPB- = ends 


Any Non Fat-based FSD can ignore, or use the fields of SectorsPerCluster, 
RootEntries, and SectorsPerFat entries for its own purposes, if necessary. 


Although, nothing can prevent a media smaller than 32MAB from using the 


Ext TotalSectors, instead of TotalSectors. For compatibility reasons, ISM 
FORMAT will use TotalSectors for media << 32MB. 


2.1.8.5 IFS Commands 


2.1.8.5.1 IFS CONFIG.SYS Function: 
2.1.8.5.1.1 IFS: 


Purpose The IFS command starts {loads and initializes) an FSD. 


Format 
IFS = {(drive:}{path}name[.ext} {parms} 

Where {drive:}(path}name{.ext} specifies the FSD to load and initialize. 
parms represents an FSD-defined string of initialization 
parameters. 
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2.1.8.6 IFS API Function Calls 


File 1/0 Function Call Summary 


DosBuf Reset 
DosChDir 
DosChyFilePtr 
DosC lose 

DoasCopy 
DosDelete 
DosDevIoCt i 
DosDupHandle 
DosEditNanme 
DosFilelo 
DosFileLocks 

DosF indC lose 
DosFindFirst 

DosF indNext 

DosF indNot i fyClose 
DosF indNotifyFirse 
DosF indNot ifyNext 
DosFsAttach 
DosFsct } 
DosMkDir 

DosMove 
DosNewSize 


DosOpen 


Flush file buffers. 

Change current directory. 

Move the fille read/write pointer. 

Close tile handle. 

Copy file 

Delete file. 

1/0 controi tor devices. 

Duplicate file handle. 

Transform source string using editing string 
Multi-function call. 

Lock/unlock a range of bytes in an opened file. 
Tecminate usage of a directory search handle. 
Find first matching file. 

Find next matching file. 

Terminate usage of a find-notify handle. 
Start monitoring directory for changes. 
Continue monitoring directory for changes. 
Attach a drive or device to an FSD. 

File system control 

Make subdirectory. 

Move a file or subdirectory. 

Change size of a file. 


Open/create a file. 
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DosQcurDir 
DosQCurDisk 
DosQFHandState 
DosQFileiInfo 
DosOQF i leMode 
DosQFsAttach 
DosQFsInfo 
DosQHandType 
DosQPathinfo 
DosQSysInfo 
DosQVerify 
DosRead 
DosReadAsync 
DosRwDir 
DosScanEnv 
DosSearchPath 
DosSelect Disk 
DosSetFileiInfo 
DosSet Fi leMode 
DosSetFllandState 
DosSetFalinfo 
DoaSet MaxFH 
DosSetPathIinfo 
DosSet Verify 
DosShutdown 


DosWrite 


OS/2 
Query 
Query 
Query 
Query 
Query 
Query 
Query 
Query 
Query 
Query 


Query 
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current directory. 


current default drive. 


file handle state information. 


file information. 


file mode. 


attached FSD information. 


file system information. 


handle type. 


path information, 


system Information 


the verify setting. 


Read from a file. 


Async 


Read froma file. 


Remove subdirectory. 


Scan environment . 
Search path. 


Select disk. 


Set file information. 


Set file mode. 


Set file handle state. 


Set file system information. 


Define new maximum file handle. 


Set path tnformation. 


Set verify setting. 


Shutdown File Systems for Power Off 


Write to a file or device. 
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DosWriteAsync Asyno write to a file or device. 


2.1.8.6.1 Application File 1/0 Notes: 


File handle values of OxFFFF do not represent actual fille handles but are 
used through-out the file system interface to indicate specific actions to 
be taken by the file system. Usage of this ‘special file handle’ where it is 
not expected by the file system will result in an error. 


Null pointers are defined to be 0x00000000 throughout this specification. 
Existing file systems that conform to the Standard Application Program 
Intectace (Standard AP!) described in this section, may not necessarily 
support all the described information kept on a file basis. When such is 
the case, FSDs are required to return to the application a null {zero} value 
for the unsupported parameter. 

An FSD may support version levels of files. 


Dates have the following format: 


Date bit 


9432109876543210 
mapping yyyyyyymummddddd 
Where: 

mm is the month (1-12) 
dd is the day of month (1-31) 


yy is number of years since 1980 


Times have the following format: 
0 
x 


4321 
xX x 


5 
m 
hh is the binary number of hours (0-23) 


mm is the binary number of minutes (0-59) 


xx is the binary number uf two-second increments 


Some API below may return device-driver/device-manager generated errors. 


Rather than listing the ercors with each API, these error codes are: 


*  RROR WRITE PROTECT - the diskette in the drive has write-protection 
. \ : 
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enabled. 


* ERROR_BAD_UNIT ~- there is a breakdown of internal consistency between 
OS/2's mapping between logical drive and device driver. Internal Error. 


* ERAROR_NOT_READY - the device driver detected that the device is not 
ready. 


™ ERROR_BAD COMMAND - there 1s a breakdown of internal consistency between 
OS/2‘s idea of the capability of a device driver and that device driver. 


* ERROR_CRC ~- the device driver has detected a CRC mismatch. 


* ERROR_BAD_LENGTH ~- there is a breakdown of internal consistency between 
OS/2‘s idea of the length of a request packet and the device driver's 
idea of that length. Internal Error. ' 


* ERROR SEEK - the device driver detected an error during a seek 
operation. 


*  ERROR_NOT DOS DISK - the disk is not recognized as being 0OS/2 
manageable. 


* ERROR_SECTOR_NOT FOUND ~ the device is unable to find the specific 
sector. 


* ERROR OUT _OF PAPER ~- the device driver has detected that the printer is 
out -of-paper. 


*  ERROR_WRITE FAULT - other write-specific error. 

* ERROR_READ FAULT - other read-specific error. 

*  ERROR_GEN FAILURE - other error. 

There are also errors defined by and specific to the device driver 
themselves. These are indicated by either OxFF or OxFE in the high byte of 
the error code. 

Error codes listed below are not complete as each FSD may generate errors 


based upon its own circumstances. The errors below are those generated by 
the IFS router and the FAT file system. 
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Format 


Where 


Returns: 


Remarks 


Named Pipe Considerations 


Microsoft Confidential 
OS/2 1.2 IFS Patent Documentation 


Application File I/0 Function Calls: 


DosBufReset - Commit file’s cache buffers: 


Flushes requesting process’s cache buffers for the specified file 
handle or for all file handles attached to that process. 


Calling Sequence: 


EXTRN DosBufReset -FAR 


PUSH WORD FileHandle ; File handle 
CALL DosBufReset 


FileHandjle is the file handle whose buffers 
FileHandle == OxFEFF, as above except 
attached to the process are flushed. 


are to be flushed. If 
that all file handles 
IF ERROR {AX not = 0) 

AX = Error Code: 


a ERROR INVALID HANDLE if Che specified file handle is 
invalid or the handle is attached to a physical device. 


® Device-driver/device-manager errors listed “------ ----- 
coc ances wHese “ on page ---~-. 
The file's directory entry is updated, {as if the file had been 


closed using DosClose), but the file remains in the open state. 


The application should be aware that usage of this function to 
flush ajl of the requesting process's cache buffers could have the 
undesireable effect of requiring the user to mount and unmount a 
large number of removable volumes. 


Performs an operation analogous to the defined 
forcing the buffer cache to disk. For named pipes, 
DosBufReset blocks the caller until atl data written by the 
caller has been successfully read by the other end. This allows 
communicating processes to synchronize their dialogs. 


one of 
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Purpose Define the current directory for the requesting process. 
Format. Calling Sequence: 
EXTRN DosChDir:FAR 
PUSH@ ASC11Z DirName ; Directory path name 
PUSH DWORD 0 3; Reserved (must be zero) 
CALL DoasChDir 
Where DirName is the ASC11Z directory path name. 
Returns: IF ERROR {AX not = 0) 
AX = Error Code: 
* ERROR FILENAME _EXCED RANGE - the directory path specified 
ia unacceptable to the FSD managing the volume. 
* ERROR PATH_NOT_FOUND - the drive letter is invalid, there 
are too many .., there are wildcards in the directory 
_ path, or a component of the directory path is not present. 
* ERROR_NOT ENOUGH MEMORY - unable to allocate storage for 
current directory 
* ERROR_DRIVE_LOCKED - the drive is locked by another 
process 
"  _ ERROR_INVALID PARAMETER - the DWORD reserved field is not 
0. 
* Device-driver/device-manager errors listed *®------ ~«---- 
a ae “ on page ---. 

Remarks If any member of the directory path does not exiat, then the 
directory path is not changed. The current directory is changed 
only for the requesting process. 
DosQSysInfo must be used by an application to detemine the 
maximum path length supported by OS/2. The returned value should 
be used to dynamically allocate buffers that are to he used to 
store paths. This will ensure that applications function 
correctly (wrt path lengths) for future versions of OS/2. The 
path length includes the drive specifier (i.e. a:), the leading 
*\" and the crailing NUL. 
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2.1.8.6.5 DosChgFilePtr - Change File Read Write Pointer: 
Purpose Moves the read/write pointer according to the method specified. 


Format Calling Sequence: 


EXTRN DosChoFilePtr:FAR 


PUSH WORD FileHandle ; File handle 

PUSH DWORD Distance ; Distance to move in bytes 
PUSH WORD MoveType Method of moving (0, 1, 2) 
PUSH® DWORD NewPointer ; New Pointer Location 

CALL DosChgFilePtr 


ee 


Where 
FileHandle is the file handle. 
Distance is the signed distance (offset) to move in bytes. 
MoveType is the method of moving (0, 1, 2). 


* lf value = 0, the pointer is moved Distance bytes (offset) 
from the beginning of the file. 


s If value =~ 1, the pointer is moved to the current location 
plus offset. 


* If value = 2, the pointer is moved to the end-of-file plus 
offset. This method can be used to determine the file’s stze. 


NewPointer is a double word area where the system returns the new 
pointer location. 


Returns: _IF ERROR (AX not = 0) 
AX = Error Code: 
” ERROR INVALID HANDLE ~ the specified handle is not valid 
in the current process, the handle is attached to a 


physical device 


* ERROR_SEEK ON DEVICE - the handle is attached to a pipe or 
character device. 


* ERROR_INVAL1D FUNCTION - the parameter MoveType is invalid 


* ERROR_NEGATIVE SEEK - the resulting position within the 
file is negative. 
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* ERROR_DIRECT ACCESS HANDLE - the handle is for a direct 


open and the resuiling position is beyond the physical end 
of the media. 


Remarks The read/write polnter ina tile 4s a signed 32-bit number. 
It 1s illegal to seek to a negative position ina file. 
It is illegal to seek on a chatacter device or pipe. 
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Purpose 


Format 


Where 


Returns: 


Remarks 


Named Pipe Considerations Closes a pipe by handle. When all 
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Closes the specified file handle. 
Calling Sequence: 
EXTRN DosClose:FAR 


PUSH WORD FileHandle ; File Handle 
CALL DosClose 


FileHandie is the handle returned by DosOpen or DosMakePipe. 
IF ERROR {AX not = 0) 
AX = Error Code: 


*  ERROR_INVALID_HANDLE ~ the specified handle is not open or 
4s attached to a physical device. : 


bd ERROR FILE NOT_FOUND - the directory entry that is thought 
to contain the name of che file doesn’t. 


* Device-driver/device-manager errors listed “------ ----- 
enna wee ee * on page ---. 


Closing a file handle causes the file to be closed, the directory 


to he updated, and all internal buffers for that file to be 
written to the media. 


handles 
referencing one end of a pipe are closed the pipe is broken. It 
the client end closes, no other process can reopen the pipe unti} 
the serving end issues a DosDisconnectNmPipe followed by a 
DosConnectNmPipe. If the server end closes, the pipe will be 
deallocated when the last client handle is closed or immediately 
Lf the pipe is already broken. 


DosQSysinfo must be used by an application to detemine the 

maximum path length supported by 0S/2. The returned value should 
be used to dynamically allocate buffers that are to be used ta 
store paths. This will ensure that applications function 
correctly (wrt path ftengcths) for future versions of OS/2. The 
path length includes the drive specifier (i.e. d:}), the leading 
"\’ and the trailing NUI.. 
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2.1.8.6.7 DosCopy - Copy file: 


Purpose Copies the specified file or subdirectory to target file or 
subdirectory 


Format Calling Sequence: 
EXTRN DosCopy:FAR 


PUSH#@ ASCII2Z SourceName 
PuSH@® ASCI1Z TarygetName 
PUSH WORD OpMode 
PUSH DWORD 0 

CALL DosCopy 


Source path name 

Target path name 
Operation mode 
Reserved (must be zero) 


Be Be Ge He 


Where SourceName 1s the ASCI1Z path name of the source file, 
subdirectory, or Character device. Wildcards are not allowed. 


Target Name is the ASCI1I2Z path name of the target file, 
subdirectory, or character device. Wildcards are not allowed. 


OpMode is a word-jength bit map that defines how the DosCopy 
function will be done. 


The bit field mapping is shown as follows: 
OpMode 54321098676543210 
bits RRRRRKRARRRRRRARAE 

E Existing Target File Disposition 

If E = 0; Do not copy the source file to the target if 
the file name already exists within the target 
directory. If a single file is being copied 
and the target already exists, an error is 
returned. 

If E = 1; Copy the source file to the target even tif 
the file name already exists within the target 
directory. 

A Append the source file to the target file’s end of data. 

jf A = 0; Keplace the target file with the source file. 
if A« 1; Append the source file to the target file’s 


end of dats. This is ignored when copying a 
directory or if the target file doesn’t exist. 
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Returns: IF ERROR {AX not = 0) 
* AX = Error Code: 

- ERROR_FILENAME EXCED_ RANGE - the Path specified tis 
unacceptable to the FSD managing the volume. 

- ERROR_PATH_NOT_ FOUND - Bither the ojd or new path can’t be 
found. 

~ ERROR_SHARING VIOLATION - One of the files is open. 

= ERROR_INSUFFICIENT DISK SPACE 

-  ERROR_ACCESS DENIED - Target of a file copy is read-only 
or target of a file copy already exists and E = 0. 

- ERROR_DIRECTORY - Cannot be copied to itself. Cannot be 
copled to a file. Cannot be copied to one of its 
subdirectories. 

-  ERROR_FILE_NOT FOUND 

-  E&RROR_NOT_DOS DISK 

-  ERROR_DRIVE_LOCKED 

-  ERROR_SHARING_BUFFER_EXCEEDED 

-  ERROR_INVALID_ PARAMETER 

Remarks The source and target may be on different drives. 
Wildcard characters are not allowed in the source or target name. 
When a subdirectory is specified to be copied and an I/O erro: 
occurs, the specific file being copied from the source to the 
target at the time of the error will be deleted from the target 
path and the DosCopy function terminated. 
When ai file ({non-directory) is specified to be copied, in the 
event of an 1/0 error, the fille will be deleted from the target 
path in replace mode, or resized to its original size in append 
mode, and the DosCopy function terminated. 
All files and/or directories {as applicable} in the source path 
are added to the target path. 
Read-only files in the target path are not replaced. When copying 
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a directory with E + @, they are ignored; when copying a 


directory with E = 1 or when copying a single file, an error is 
returned. 


When TargetName indicates a device name, SourceName must indicate 
a file, not a directory. 


When copying a single file with A «1 (Append mode), the operation 
will proceed even 1f the file exists and & = 0. In other words, 
the E bit {Is only significant when replacing, not when appending. 


OpMode bit flags A and E are undefined (ignored) when the target 
is a device. 


DosCopy will copy the source's attributes (date of creation, time 
of creation, ...}) lo the target. 


DosCopy will capy the source's EAs to the target when creating a 
new subdirectory, when creating a new file, or when replacing an 
existing file. le will not copy the source’s EAs to an existing 
file when appending to it of to an existing directory when copying 
files to that directory. If the file system of the dest ination 
does not support EAs, DosCopy will terminate the operation and 
return the error. 


DosCopy takes the source subdirectory structure (one node) and 
CREATE/APPEND a similar directory structure to a destination node: 


DosCopy C:XYZ DO: \DEF 


CixXY¥Z D:\DEF 
/ \ f/f N 
A B + <no D:\DEF> «> A B 
/N /\ 
Cc D Cc D 
eT 
C XYZ D: \DEF D:\DEF 
/ \ , AN / iN 
A B + E B => A E 8B 
{/\ | “iN 
8) E ec F D 


SubdireclLories from the source path "C:\KYZ\B" of the second 
example, are appended for logically added} to like-named 
subdirectories in the target path “D:\DEF\B". 


A second example of DosCopy operation: 
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DosCopy C:\X¥Z D:\Xy¥2 


Csroat 
‘\ fl 
A XYZ xX Y 
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=> 
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O:root Dsroot 


Dzroot D:root 
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2.1.8.6.8 DosDelete - Delete a File: maximum path length supported by OS/2. The returned value should 
be used to dynamically allocate buffers that are to be used to 
store paths. This will ensure that applications function 
correctly (wrt path lengths) for future versions of OS/2. The 
Path length includes the drive specifier (i.e. d:), the leading 
*\"¥ and the tralling NUL. 


Purpose Removes a directory entry associated with a filename. 


Format Calling Sequence: 


met fee! Gee Go eee toe 


EXTRN DosDelete:FAR 


PUSHE ASCIIZ FlleName ; Filename path 
PUSH BWORD O 3; Reserved (must be zero) 
CALL DosDelete 


Where FileName is the ASCIIZ file name. 
Returns: IE ERROK (AX not - 0) ’ 
AX - Error Codes: 


a ERROR FILENAME EXCED RANGE - the path specified is 
unacceptable to the FSD managing the volume. 


* ERROR PATii NOT FOUND - the drive letter is invalid, there 
are tvo many .., Chere are wildcards present, or a 
component of the directory path is not present. 


e ERROR FILE NOT FOUND - the filename at the end of the path 
is not found. 


® ERROR ACCESS DENIED - the path specified a directory or a 
device, or the file is read-only. 


. ERROR SHAKING VIOLATION - Che file specified is currently 
in use, 


* ERROR SHARING BUFFER EXCEEDED ~ there is not enough memory 
to hold sharing information. 


. Device-driver/device-manager errors listed ®--2--- ----- 
weer teen ween “ on page --~. 


Remarks Wildcard characters are not allowed in any part of the ASCII2 
string. 


Read-only tiles cannot be deleted by this call. To delete a 
read-only file, you must first use function DosSetFileMode (Set 
File Mude) tu change the file’s read-only attribute to Q, then 
delete the file. 


DosQSysinto must be used by an application to detemine the 
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2-1.8.6.9 DosDevl0Ct] - 1/0 Control for Devices: = ERROR_INVALID FUNCTION - the specified function is illegal! 


for the particular category and handle. 
Purpose Perform control functions on the device specified by the file or 


device handle. * ERROR_INVALID CATEGORY - the specified category is illegal 
for the particular function and handle. 


Format Calling Sequence: 
* ERROR INVALID DRIVE -~- the drive specified in a 
EXTRN DosDevIlIOCt ]:FAR set-logical-drive-map call is not supported by the device 
driver. 
PUSH@ OTHER Data ; Data area 
PUSH@ OTHER ParmList ; Command arguments °, ERROR_INVALID PARAMETER - (DosDevIOCtl2) a O length was 
PUSH WORD Function ; Device function specified with a non-null pointer for either Data or 
PUSH WORD Category 3; Device calegory ParmList. 
PUSH WORD DevHandle :; Specifies the device 
CALL DosDevlOcerl * Device-driver/device-manager errors listed “------ ----- 


See. SSeS Soa “ on page ---. 


EXTRN DosDevIOCtl2:FAR 


Remarks This function provides a generic, expandable IOCTL facility. 


PUSH@ OTHER Data Data area 


PUSH WORD DataLength : Data area length A null (zero) value for Data specifies that this parameter is not 

PUSH@ OTHER ParmList ; Command arguments defined for the generic [OCTL function being specified. A null 

PUSH WORD ParmListLength ; Command arg’s list length value for Data causes the value passed in DataLength to be 

PUSH WORD Function é Device funct lon ignored. 

PUSH WORD Category ; Device category 

PUSH WORD DevHandle ; Specifies the device A nul] (zero) value for ParmList specifies that this parameter is 

CALL DosDevIoOcti2 not defined for the generic I0CTL function being specified. A 
nul} value for ParmList causes the value passed in ParmListLength 

where Data is a dala area. to be ignored. 

DataLength is the length of the data buffer. The kerne] will format a generic IOCTL packet and call the device 
driver. Since v1.0 and vil.l device drivers do not understand 

ParsmList is a command-specific argument List. generic 1O0CTL packets with DataLength and ParmListLength, the 
kernel will not pass these fields to the device driver. Device 

ParmListLength is the length of the command-specific argument drivers that are marked as being level 2 or higher (see device 

list. driver header spec) must support receipt of the generic I0CTL 


packets with associated length fields. 
Function is the device-specific function code. The valid rcange is 
0 tao 255. It is illegal to pass in a non-null pointer with a zero length. 
Category 1s the device category. The valid cange is 0 to 255. 
DevHandle is a device handle returned by DosOpen. 
Returns: IF ERROR (AX not - 0) 
AX - Erroc Code: 
: ERROR INVALID HANDLE - the handle specified is either not 
in use, is altached to a physical device and category 9 is 


not specified or is not attached to a physical device and 
category 9 is specified. 
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2.1.8.6.10 DosDuptlandle - Duplicate a File Handle: 


Purpose Returns a new file handle for an open file that refers to the same 
File ac the same position. 

Format Calling Sequence: 
EXTRN DosDupHandle:FAR 
PUSH WORD OldFileHandle ; Existing file handle 
PUSH@ WORD NewFileHandle ; New file handle 
CALL DosDupHiandle 

Where OldtileHandle is the current file handle. 
NewFileHandle is a word file handle that is made the duplicate of 
OldFileHandle or is OxFFFF. A value of Oxf FFF causes the DOS to 
allocate a new file handle and use that as the destination of the 
duplication. Otherwise, the function uses NewFileHandle as the 
destination of the duplication. 

Returns: IF ERROR (AX not = 0) 

AX = Error Code: 

» ERROR INVALID HANDLE - the OldFileHandle is invalid or is 
attached to a physical device. 

* ERROR_TOO MANY OPEN FILES - NewFileHandle is OxfFFF and 
all handles for the process are in use. 

* ERROR_INVALID TARGET_HANDLE - the specified NewFileHandle| 
is beyond the range allocated to the process, either by 
default, oc by DOSSETMAXFH. 

e Device-driver/device-manayger errors listed “------ ----- 
were See ee seen “ on page ---. 

Remarks Duplicating the handle duplicates and ties all handle-specific 
information between OldfileHand!ie and NewFiletiandle. 
A tile handle value other than OxFFFF specitted in NewF!ileHandle 
causes that tile handje to be closed before it 18 redefined as the 
duplicate of OldFileliandle. 
The valid values tor NewkileHandle include: OxFFFF, 0x0000 
(Standard itnput), Ox0001 (Standard Output), O0x0002 (Standard| 
Error), oc the handle of any currently open file. Avoid using 
other arbitrary values. 
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If you move the read/write pointer of either handle by a Doskead, 
DosWrite, or DosChgFilePtr function call, the pointer for the 
other handle is also changed. 


Issuing a DosClose against a file handle does not affect the 
duplicate handle. 
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* 2.1.8.6.11 DosEdltName - Transform source string using editing string: 


* Purpose Transform a source string into a destination string using an 


a editing string and OS/2 meta editing semantics. 
* Format Calllng Sequence: 
a EXTRN DosEditName :FAR 
« PUSH WORD EditLevel ; Level of meta editing semantics 
* PUSHE ASCII2Z SourceString ; String to transform 
= PUSH@ ASCIIZ EditString 3 Editing string 
* PUSH@® OTHER Target Buf :; Destination string buffer 
* PUSH WORD TarygetBufLen ; Destination string buffer length 
. CALL DosEditName 
* Where EditLevel is the version of meta editing semantics to use in 
. transforming the source string. 

a It EditlLevel value is 0x0001, then OS/2 version 1.2 editing 
. semantics are used. 
> So.rceString is the ASCIIZ string to transform. It should 
® contain just the component of the pathname to edit, not the entire 
s path. 
. EditStcing is the ASCI1IZ string to use for editing. 
. TargetBuf is the buffer to store the resulting ASCIIZ string in. 
® TargetBufLen is the length of the buffer to store the resulting 
’ string in. 


* Returns: IF ERROR {AX not = 0) 
sd AX = Error Code: 


] =  ERROR_INVALID PARAMETER - the EditLevel is invalid. 


| s ERHOR INVALID NAME - the SourceString or EditString 
{ contains a drive letter or path characters. 
* Remarks Typical uses of this API are copy and rename/move. For a 
id SourceString “foo.bar" and an EditString “*.baz", the destination 
" string is “foo.baz"* for OS/2 version 1.2 meta editing semantics. 
{ The destination string will be uppercased. 
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+ name. Reftype = 0 indicates a handle; Reftype = 1 indicates that 
¢ FileRef points to an ASCIIZ2 name of a file or directory . 
+ FileRef is a pointer to a WORD handle that was obtained >from 
+ DOSOPEN/DOSOPEN2, or to an ASCI1I2 name of a file or directory . 
+ EntryNum is the ordinal of the entry in the BA list from which to 
+ start copying information into EnumBuf . 
t The EntryNum value of zero is reserved, and the first EBA is 
+ indicated by a value of 1 . 

EnumBuf is a pointer to the buffer where the requested information 
4 iz returned . 
+ EnumBufSize is the size of EnumBuf . 


Microsoft Confidential 
OS/2 1.2 IFS Patent Documentation 


+ 2.1.8.6.12 DosEnumAtt ribute - Ennumerate the extended attributes: 


¢ Purpose Ennumerates information for a specific file or subdirectory . 





+ Format Calling Sequence: 

+ EXTRN DosEnumAttribute:FAR 

+ PUSH WORD RefType z Type of reference 

+ PUSH@ OTHER FileRef 3 Handle or Name 

+ PUSH DWORD EntryNum ¢ Starting entry in EA List 

¢ PUSH@ OTHER EnumBuf 3; Data buffer 

+ PUSH DWORD EnumBufSize ?: Data buffer size 

+ PUSH@ DWORD  EnumcCnt 7; Count of entries to return 

+ PUSH DWORD InfoLevel ¢ Level of information requested 
+ PUSH DWORD 0 3; Reserved (must be zero} 

¢ CALL DosEnumAttribute 

+ Where RefType indicates whether FileRef points to a handle or an ASCIIz 


+ Enumnt is, on input, the number of EAs whose information has been 
t requested. The system will change this to the number actually 
t returned. An EnumCnt of -1 is treated specially in that it will 
+ return as many entries as will fit in the buffer specified . 

+ InfoLevel is the level of information required . 


t Level 0x00000001 information is returned in the following format: 
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struct | 
unsigned char reserved; /* must be 0 
unsigned char cbName; /* length of name excluding NU 
unsigned short cbhValue; /* length of value 
unsigned char szName{]); /* asciiz name 


The fields in the structure are on a One-to-one mapping for the 
fields in an FEA structure. 


The information for the next EA will be stored adjacent ta the 
Previous one. An application that wishes to continue on from one 
DosEnumAttribute call would have to set EntryNum to the previous 
value plus the returned value in EnumCnt . 


The size of buffer needed to hold an EA can be obtained from the 
ennumerated information. An EA would occupy: 


one byte {for fea_Heserved) + 

one byte (for fea_cbName} ¢ 

two bytes {for fea_cbValue) ¢ 

value of cbName (for the name of the EA) + 


one byte (for terminating NULL in fea_cbName) + 
value of cbValue (for the value of the EA) 


Heturns: IF ERROR (AX not = 0) 


AX = Error Code: 


LS ERKOR_FILENAME EXCED RANGE - the path specified is 
unacceplable to the FSD managing the volume. 


. ERROR_INVALID HANDLE - the handle is not in use or is 
attached to a physical device. 


. ERROR ACCESS DENIED - the handle is opened as write-only. 


. ERROR _PATH_NOT FOUND - a component of FileRef is not 


found. 

: ERROK NUT ENOUGH MEMORY - the specified bufter is too 
short for che returned data. 

7 ERROR_INVALID LEVEL - the specified InfoLevel is not 
supported. 

* ERROR INVALID PARAMETER - an invalid parameter was 
specified. 
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* ERROR_BUFFER_OVERFLOW - the buffer is not big enough to 
hold data for even one Extended Attribute. 


*  Device-driver/device-manager errors listed “------ Shateteher 
Sees Seem meme “ on page --- . 


It is important to note that the use of EntryNum in no way 
guarantees the specific ordering of the EAs. It is only a tool to 
ennumerate the EAs, and should not be used to “back up to the nth 
EA", since the EAs are subject to change by other tasks. So, for 
example, the EA returned when EntryNum is 11 may not necessarily 
be the EA returned when EntryNum is 11 for a subsequent call if 
another task had performed a SET operation on the EAlist. 


No explicit EA sharing ts done for DosEnumAttribute. Implicit 
sharing exists if the caller passes in the handle of an open file, 
since sharing access to the associated file is required to modify 
its BAs. No sharing is done if the caller passes in the pathname. 
This means that if some other process is editing the EAs, and 
changes them between two calls to DosEnumAttribute, inconsistent 
results may be returned (i.e. see same same value twice, miss 
seeing values, etc.) To prevent the modification of EAs for the 
handle case, make sure that the file is open in deny-write mode. 
To prevent the modification of EAs for the pathname case, open the 
file in deny-write mode before calling DosEnumAttribute. For the 
directory name case, no sharing is possible. 


It should be noted that for RefType = 1, the EAs returned by this 
API are current only when the cal] was made, and they may have 
been changed by another thread or process in the meantime. 
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2.1.8.6.13 DosFileIO - File 1/0: 


Purpose Perform multiple lock, untock, seek, read, and write 1/0. 

Format Calling Sequence: 
EXTRN DosFilelO: FAR 
PUSH WORD FileHandle 7 File handle 
PUSH@® OTHER CommandLi st ¢ Per to command buffer 
PUSH WORD CommandListLen ; Length of command buffer 
PUSH@ WURD ErrorOlfset : Ptr to command error offset 
CALL DosFilelO 

Where FileHandle is the handle of the file of interest. 
CommandList is a list that contains entries indicating what 
commands will be performed. The operations (CmdLock, CmdUnlock, 
CnadSeek, CmdIO} ace performed as atomic operations until all are 
complete or until one fatis. CmdLock allows a multiple cange lock 
to be executed as an atomic operation. Each operation be 
guaranteed Co execute in one plece. Unlike CmdLock, CmdUnlock 
cannot fail as long as Che parameters to it are correct, and the 
calling application had done a Lock earlier, so it can be viewed 
as atomic. 


Foc CmdLock, the command format is: 


CmadLock Struc 


Cmd dw 0 ; O for lock operations 
LockCnt dw ? 3; Number of locks that follow 
TimeOut dd ? 3; ™s timeout for success of all locks 


CadLock Ends 


which is followed by a series of records of the following format: 


Lock Struc 

Share cw ? ¢ 0 for exclusive, 1! for read-only access 
Start dd ? 3; start of locked region 

Length dd ? z length of locked region 

Lock Ends 


lf a lock within a CmdLock causes a timeout, none of 
locks within the scope of CmdLock are in force since 
operation is viewed as atomic. 


CmdLock . TimeOut is the count in milliseconds, until 
requesting process is to resume execution if the requested 
are not available. The meaning of the values specified are: 


the other 
the lock 


the 
locks 


* OxFFEFFFFF means the process will wait indefinitely until the 


requested locks become available. 
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‘ Ox00000000 means return immediately to the requesting process 


* Otherwise, CmdLock.TimeOut is the number of milliseconds to 


wait until the requested locks become available. 


Lock.Share defines the type of access other processes may have to 


the file-range being locked. 


* If Lock.Share == 0, other processes have ‘No~Access' to 
locked range. The current process will have both read 
write access to the locked range. No region with Lock.Share 


== Q may overlap with any other locked region. 


a If Lock.Share == 1, other processes have ‘Read-Only’ access to 


the 
and 


the locked range. The current process will have ‘Read-Only’ 


access to the locked range also. A range locked with 
Lock.Share == 1 may overlap with other ranges locked with 
Lock.Share == 1, but may not overlap with other ranges locked 


with Lock.Share == 0. 


For CmdUnlock, the command format is: 


CmdUnlock Struc 
Crd dw 1 
UniockCnt dw ? 
CadUnlock Ends 


1 for unlock operationa 
Number of unlocks that follow 


which is followed by a series of records of the following format: 


UnLock Struc 
Start dd ? 
Length dd ? 
UnLock Ends 


start of locked region 
length of locked region 


For CmdSeek, the command format 13: 


CmdSeek Struc 


Crd dw ? ; 2 for seek operation 
Method dw ? ; 0 for absolute, 
¢ 1 for relative to current, 
: 2 for relative to EOF. 
Position dd ? : file seek position or delta 
Actual dd ? ¢ actual position seeked to 


CmdSeek Ends 


For CmdIO, the command format is: 


Cmdi IO Struc 
Cmd dw ? : 3 for read, 4 for write 
Buffer@® dd ? ¢ ptr to the data buffer 
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BufferLen dw ? ¢ number of bytes requested 

Actual dw 2? ¢ number of bytes actually 
3 transferred 

Cmd lO Ends 


CammandListLen is the length in bytes of CommandLisc. 


ErcorOffset points to where the system stores the byte offset 
relative to the start of the record of where an error occurred. 


Returns: IF ERROR {AX not «= 0) 

AX = Error Code: 

* ERROR_INVALID PARAMETER - invalid command 

* ERROR ACCESS DENIED - the file is not accessible because 
another process has access to it. 

* ERROR_SHARING BUFFER EXCEEDED - there is not enough memory 
to hold sharing information. 

* ERROR_INTERRUPT - the current thread received a signal. 

* ERROR_SEEK ON_DEVICE - the handle is attached to a pipe or 
character device. 

*® ERROR_NEGATIVE_SEEK - the resulting position within the 
file is negative. 

s ERROR_DIRECT_ACCESS HANDLE ~ the specified handle is 
opened with the direct open bit set. 

® ERROR_INVALID_HANDLE - the file handle specified is not in 
use or is atlached to a physical device. 

# ERROR_LOCK VIOLATION - a lock operation timed out or a 
read/write operation encountered a lock. 

* Device-driver/device-manager errors listed %------ ----- 
.<SS= eee eee s “ on page -~-. 

Remarks This function provides a simple mechanism for combining the 
following operations into a single request and providing improved 
performance particularly in a networking environment: 
® unlocking and locking of multiple file ranges 
s changing of the file posilion pointer 
* read and/or write 10 
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Provides a simple mechanism for excluding other processes 
read/write or write access to regions of the file. If another 
process attempts to read or write a ‘No-access’ region, or 
attempts to write in a ‘Read-only’ region, the system cal} will 
return an error indicating exclusion to that region. If the 
time-out occurs before the locking can be completed, the function 
returns to the caller with an unsuccessful return code. 


The caller may return after the timeout period has expired without 
receiving an ERROR SEM TIMEOUT. Therefore, semaphore timeout 
values should not be used for exact timing and sequencing. 


A range to be locked must first be cleared of any locked subranges 
oc locked overlapping ranges. 


2.0 Functional Characteristics 136 


00073 


cv SVE SIP O da 


Microsoft Conf tdential 
OS/2 1.2 IFS Patent Documentation 


2.1.8.6.14 DosFileLocks - File Lock Manager: 


Purpose Unlock and/or lock a range in an opened file. 
Format Calling Sequence: 
EXTRN DosFi leLocks:FAR 
PUSH WORD FlleHandle 3; File handle 
PUSH® OTHER UnLockRange ; Unlock range 
PUSH@ OTHER LockRange ; lock range 
CALL DosFileLocks 
tihere FileHandle 1s the file handle. 
UnLockKange identifies the range in the file of the region to be 
unlocked: 
UnlockRange struc 
FileOffset dd ? : Offset where unlock begins 
RangeLength dd ? i length of region unlocked 
UnlockRange ends 
A null pointer (a dwurd of zero} to UnlockRange specifies that 
unlocking is not required. 
LockRange idenitifies the range in the f£tle of the region ta he 
locked: 
LockRange struc 
FileOffset dd ? ; offset where tock begins 
RangeLength dd 2 | length of region lacked 
LockRange ends 
A null pointer {a dword of zero) to LockRange specifies that 
locking is not required. 
Returns: IF ERROR {AX not = 0) 

AX = Error Code: 

: ERROR_INVALID HANDLE - handle specified is not open or is 
altached to a physical device. 

. ERROR LOCK VIOLATION - the range specified for locking 
overlapped a previously locked = range or the range 
specified for unlocking did not exactly match a previously 
locked range. 

* ERROR_SHARING BUFFER EXCEEDED - there is no more room for 
locks. 

Remarks This function provides a simple mechanism for unlocking and/or 
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locking a file range. 


If unlocking is specified, the function first unlocks the 
specified area using UnLockRange. After UnlockRange is 
processed, then the locking of a range (if specified via LockRange 
), is done. 


Closing a file with locks still in force causes the locks to be 
released in no defined order. 


Terminating with a file open and having issued Jocks on that file 
causes the file to be closed and the locks to be released in no 
defined order. 


Provides a simple mechanism for excluding other processes 
read/write access to regions of the file. The locked regions can 
be anywhere in the logical file. Locking beyond end-of-file is 
not an error. It is expected that the time tn which regions are 
locked will be short. Duplicating the handle duplicates access to 
the locked regions. Access to the locked regions is not 
duplicated across the DosExecPgm system call. The proper method 
for using locks is not to rely on being denied read or write 
access, but attempting to lock the region desired and examining 
the error code. 


A range to be locked must first be cleared of any locked subranges 
or locked overlapping ranges. 
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2.1.86.6.15 DosFindClose - Close Find Handle: 


Purpose Closes the association between a directory handle and a 
DosFindFirst or DosFindNext directory search function. 
Format Calling Sequence: 
EXTRN DosFindClose:FAR 
PUSH WORD DirHandle ; Directory search handle 
CALL DosFindClose 
Where 
Dirllandle is the handle previously associated by the system with 
a DosfindPirst ar DosFindNext directory search function. 
Returns: IF ERROR {AX not « 0) 
AX < Error Code: 
* ERROR_INVALID HANDLE - the specified DirHandle is invalid. 
Remarks When DosFindClose is issued, a subsequent DosFindNext for the 
closed DicHandle will fail unless an intervening DosFindFirst has 
been issued specifying DirHandle. 
DosQSysInfo must be used by an application to detemine the 
maximum path length supported by OS/2. The returned value should 
be used to dynamically allocate butfers that are to be used to 
store paths. This will ensure that applications function 
correctly {wrt path lengths) for tuture versions of OS/2. The 
path length includes the drive specifier (i.e. dz), the leading 
*\' and the trailing NUL. 
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2.1.8.6.16 DosFindFirst - Find First Matching File: 


Purpose Finds the first filename that matches the specified file 
specification. 
Format Calling Sequence: 
EXTRN DosFindFirst:FAR 
PUSH® ASCI12Z FileName 3 File path name 
PUSH@ WORD Dirllandle s Directory search handle 
PUSH WORD Attribute 3 Search attribute 
PUSH@ OTHER ResultBuf ; Result buffer 
PUSH WORD ResulltBufLen ; Result buffer length 
PUSH@® WORD SearchCount 3; # of. entries to find 
PUSH ODRORD 0 z; Reserved (must be zero) 
CALL PDosFindFirst 
EXTRN DosFindFirst2:FAR 
PUSH@ ASCTIZ FileName 5 File path name 
PUSH@ WORD DirHandle z Directory search handle 
PUSH WORD Attribute ; Search attribute 
PUSH@® OTHER Result buf ; Result buffer | 
PUSH WORD ResultBufLen ; Result buffer length 
PUSH@ WORD SearchCount ; €t of entries to find 
PUSH WORD FileInfolevel ; File data required 
PUSH DWORD 0 ; Reserved (must be zero) 
CALL DosFindFirst2 
Where FileName is the ASCI1Z path name of the file to be found. 
DirHandle is the directory handle associated by the DOS with this 
specific request. A ODirHandle value of 0x0001 1s defined to be 
élways available. A DircHandle value of OxfFEF indicates to 
allocate a handle to the user. The handle is returned by 
overwriting the OxFFFF. Reuse of this DirHandle in another 
DosFindFirst closes the association with the previously related 
DosFindFirst and opens a new association with the current 
DosFindFirst. 
FileInfolevel is the level of file information required. 
DOSFINDFIRST (and DOSFINDNEXT on handles returned by DOSFINDFIRST) 
always returns level 0x0001 information. 
Level ‘n’ File information is returned in the format described in 
ResultBuf. 
* If FileInfoLeve! value is 0x0001, then iff Attribute is set for 
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hidden, system files, or directory files, it is considered as 
an inclusive search. All normal file entries plus all entries 
matching the specified attributes are returned. To look at 
ali directory entries except the volume label, Attribute may 
be set to hidden + system + directory (all 3 bits on). 


Attribute is the attribute used in searching for the file. 
Attribute cannot specify the volume label. Volume labels may be 
queried using DosOFsInfo. 


ResultBuf is where the FSD returns the results of the qualified 
directory search. The information returned is guaranteed to be at 
least as accurate as the most recent DosClose or DosBufReset. 


For level Ox0001, directory information (find record) is returned 
in the following format; 


Struct { 
unsigned short dateCreate; 
unsigned short timeCreate; 
unsigned short dateAccess; 
unsigned short timeAccess; 
unsigned short dateWrite; 


unsigned short CimeWrite; 
long cbhEOF; 
long cbAlloc; 


unsigned short attr; 
unsigned char cbName; 
unsigned char szName[]}; 


For level Ox0002, the cbhList fleld is added to the level 0x6001 
Structure, and returned in the following format: 
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struct { 
unsigned short dateCreate; 
unsigned short timeCreate; 
unsigned short dateAccess; 
unsigned short timeAccess; 
unsigned short dateWrite; 
unsigned short timeWrite; 
long CcbEOF; 
lang cbAl loc; 
unsigned short attr; 
unsigned long cbList; 
unsigned char cbName; 
unsigned char szName()}; 

}; 


The cbList field can be used to calculate the size of the buffer 
necessary for level 0x0003. 
For level 0x0003, ResultBuf is an EAOP structure on input. 
fpGEAList points to a GEA list defining the attribute names whose 
values will be returned. fpFEAList is ignored. In case of error, 
offError will point to the offending GEA entry. 
On output, ResultBuf will contain the EAOP structure (unchanged) 
followed by a packed set of records that consist of the attributes 
record described in level 0x0001, excluding the cbhName and szName 
fields, followed by a an FEALIst structure followed by a byte 
length of the name of the object followed by the asciiz name of 
the object matched by the input pattern. 
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Space to hold it. For the buffer overflow case, cbList will 
contain the size of the entire EA set for the file, even if only a 


fae SSS Te Se See, ea eRe aS a + sobset of its attributes were requested. 
| | 
| EAOP STRUCTURE | If a particular attribute is not found attached to the object, 
| i there will be an FEA structure containing the name of the 
aa aaa a aca a aca al < attribute but with a zero-length value. 
l i 
j LEVEL OxOB001t ATTRIBUTES | ResultBufLen is the length of Result Buf. 
1 i 
Pow H Meme www mwn nema nn aww onan nnen < SearchCount is the number of matching entries requested in 
{ cbList { ResultBuf. The file system uses this field to store the number ot 
a aaa aaa < entries actually returned. 
t ; 
t FEA LIST { Returns: IF ERROR {AX not = 0} 
l I ' 
2S SSR Sees sasaki meno ess sae ee < AX = Error Code: 
1 cbName | 
Pore wen ween nn nn sew nnereneae < * ERROR_INVALID_ PARAMETER ~- the search attribute is invalid 
| ; or the specified search count is 0. 
i FILENAME { 
! i * ERROR_INVALID_HANDLE - the handle specified is never 
Pe meen ence mee renter enn nee nenaaa= < allocated. 
/ | 
; LEVEL 0x0001 ATTRIBUTES ( *  ERROR_FILENAME EXCED RANGE - the path = apecified is 
; 1 unacceptable to the FSD managing the volume. 
Dre en rn nn ee enn enn eee = < 
1 cbhList t ‘ * ERROR_META_EXPANSION TOO LONG - the FAT FS is unable to 
Perm nt ee ee mmm nn nen nen nena < expand meta characters correctly. 
' ; 
i FEA LIST \ * ERROR_PATH_NOT_ FOUND - the drive letter is invalid, there 
1 | are too many .., there are wildcards present before the 
Deen ne ee en ne nn enn ene < last component, or a component of the directory path is 
| cbName j not present. : 
De er en nnn en eee ren ane < 
i 1 * ERROR_BUFFER_OVERFLOW - the specified buffer is too smal! 
i FILENAME t to support a single entry. 
; 
$a rn oe re nn re en eee t as ERROR_NO MORE SEARCH HANDLES - there are too many search 
: handles in use for the current process. 
; * ERROR_NO MORE FILES - there are no matching files 
remainder of files found 
e Device-driver/device-manager errors listed "------ ----- 
ee ee ee *" on page ---. 
Figure 9. DOSFINDFIRST return buffer format ® ERROR_INVALID EA NAME - there is an illegal character in 
an EA name. The offErroc field points to the offending 
GEA. 
Even if there is not enough room to hold all the requested 
information, (ie ERROR BUFFER OVERFLOW) the cbList field of the * ERROR_EA_LIST_ INCONSISTENT - the cbList does not match the 
FEA list will still be valid, assuming there’s at least enough|+ sum of the lengths of the GEA structures. 
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* ERROR_HUFFER OVERFLOW - 
hold the information, 
entry that was found. 


The buffer waa not big enough to 
excluding the EAs, for even one 


*  ERROR_EAS DIONT FIT - The buffer was not big enough to 
hold the EAs for the first matching entry being returned 
in the buffer. This occurs for infolevel 3 where the first 
matching entry cannot be returned together with its EAs 
because the EAs don’t fit in the buffer. 


DosFindNext uses the directory handle to 
DosFindFirst. 


repeat the related 


The filename in FileName can contain wildcard characters. 


Any non-zero return code except ERROR_EAS DIDNT _ FIT indicates no 
handle has been allocated. This includes such “non-error® 
indicators a3 ERROR NO MORE FILES. 


in the case of ERROR EAS DIDNT_FIT, a search handle is returned, 
and a subsequent call to DosFIndNext will get the next matching 
entry in the directory. You may use DosQPathInfo to retrieve the 
FAs for the matching entry by using the EA arguments that were 
used for the FindFirst2 call and the name that was returned by 
FindFirst2. 


In the case of ERROR_EAS DIDNT FIT, only information for the first 
matching entry is returned. This entry is the one whose EAs did 
not fit in the buffer. The information returned is in the format 
of that returned for infolevel 2. No furthec entries are returned 
in the buffer even if they could fit in the remaining space. 
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2.1.8.6.17 DosFindNext - Find Next Matching File: 


Purpose Finds the next directory entry matching the name that is specified 
on the previous DosFindFirst or DosFindNext function call. 

Format Calling Sequence: 
EXTRN DosF indNext :FAR 
PUSH WORD DirHandle 3 Directory handle 
PUSH@ OTHER Result Buf ¢ Result buffer 
PUSH WORD Result Buf Len ? Result buffer length 
PUSH@ WORD SearchCount ¢ € of entries to find 
CALL DosFindNextc 

Where DirHandle is the handle (previopsly returned by 00S) assoctated 
with a previous DosFilndFirst or DosFindNext function call. 
ResultBuf is where the FSD returns the results of the qualified 
directory search. The information returned is quaranteed to be at 
least as accurate as the most recent DosClose or DosBufReset. 
For the continuation of an infolevel 3 search, this buffer should 
contain input in the same format as a DosFindFirst2 infolevel 3 
search. 
ResultBufLen is the length of ResultBuf. 
SearchCount is the number of matching entries requested in 
ResultBuf. The file system uses this field to store the number of 
entries actually returned. 

Returns: IF ERROR {AX not = 0) 

AX ~ Error Code: 

* ERROR_INVALID PARAMETER - a search count of zero is 
specified. 

*  ERROR_INVALID HANDLE - the specified search handle is not 
in use. 

* ERROR_BUFFER_OVERFLOW - the specified buffer was not big 
enough to hold the information, excluding the EAs, for 
even one entry that was found. 

* ERROR_EAS_DIONT FIT - ‘The buffer was not big enough to 
hold the EAs for the first matching entry being returned 
in the buffer. This occurs for infolevel 3 where the first 
matching entry cannot be returned together with its EAs 
because the EAs don’t fit in the buffer. 
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* ERROR_NO MORE FILES ~ Chere are 
files. 


no more files matching 


* Device-driver/device-manager errors listed *------ -- ated 


Seek SSS: me ser * on page ---. 


If no more matching files are found, an error code is returned. 


If an ERROR BUFFER OVERFLOW error is returned, the further calls 
to DosFindNext will start the search trom the same entry. 


If an ERROR_EAS DIONT FIT error is returned, then the buffer was 
too small to hold the EAs for the first matching entry being 
returned. A subsequent cal! to FindNext will get the next matching 
entry. This enables the search to continue if the EAs being 
returned are tou big to fit in the bufter. You may use 
DosQPathInfo to retrieve the EAs for the matching entry by using 
the EA arguments that were used for the FindFirst2 call and the 
Mame that was returned by FindFirst2. 


In the case of ERROR EAS DIONT_FIT, only information for the first 
matching entry is returned. This entry is the one whase EAs did 
not fie in the buffer. The Information returned is in the format 
of that returned for infolevel 2. No further entries are returned 
in the buffer even if they could fit in the remaining space. 
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2.1.8.6.18 DosFindNotifyClose - Close Find-Notify Handle: 


Purpose Closes the association between a ‘’Find-Notify’ handle and a 
DosFindNotifyFirst or DosFindNotifyNext function. 

Format Calling Sequence: 
EXTRN DosFindNot ifyClose:FAR 
PUSH WORD DirHandle ; Find-notify handle 
CALL DosFindNotifyClose 

Where 
DirHandle is the handle previously associated by the system with 
4 DosFindNotifyFirst or DosFindNotifyNext function. 

Returns: IF BRROR (AX not = 0} 

AX = Error Code: 
*  ERROR_INVALID_HANDLE - the specified handle is not in use. 

Remarks When DosFindNotifyClose is issued, a subsequent DosFindNot lfyNext 
for the closed DirHandle will fail unless an intervening 
DosFindNotifyPirst has been issued specifying DirHandle. 
If a DosFindNotifyClose is issued on a DirHandle while a thread 
that issued a DosFindNotifyNext for the same DirHandle is waiting 
for the requested changes or the timeout, the close operation wi) 
abort the DosF indNot i fyNext and will succeed, The 
DosFindNotifyNext thread will return immediately with an 
ERROR_FINDNOTIFY HANDLE CLOSED return code. If the 
DosFindNotifyNext call has timad-out or counted the requested 
number of changes but has not returned, the DosFindNotifyClose 
thread will sleep unti)] the next operation completed. 
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2.1.8.6.19 DosFindNotifyFieste - Start monitoring directory for changes: 


Purpose 


Format 


Where 


{| Returns: 


Start monitoring a dicectory for changes. 


Calling Sequence: 


EXTRN DosFindNot ifyFirst: FAR 


PUSH@ ASCII2Z PathSpec 
PUSH@ WOKD DirHandle 
PUSH WORD Attribute 
PUSH@ OTHER Result But 
PUSH WORD Result Bullen 
PUSHE WOKD ChangeCount 
PUSH WORD Filelnfolevel 
PUSH DWORD ‘TimeOut 

PUSH DWORD GO 

CALL DosFindNot ifyFirst 


Path spec 

Path handle 

Search attribute 
Result buttec 

Hesult buffer length 

# of changes required 
Fille data required 
Duration of cail 
Reserved (must be zero) 


we Be Be Be Be Be Be Be HS 


PathSpec is the path name to be monitored for directory changes. 


DirHandie tis the handle returned by OS/2 which is associated with 
this request. 


FileInfolevel is the level of file Information required. A value 
of 0x000)1 returns no information to ResultBuf. Values other than 
0x0001 are not suppurted in this release of OS/2. 

Attribuce is the file attribute used in qualifying the files 
and/or directories to be monitored. Attribute cannot specify the 
volume label. Volume labels may be queried using DosQFsInfo. 


ResultBuf is where the filesystem returns the results of the 
PathSpec monitoring. 


ResultBufLen is the length of HesultHuf. 

ChangeCount is the number of changes required to directories or 
files that match the PathSpec target and Attribute. The file 
system uses this field to return the number of changes that 


actually occurred. 


TimeOut 18s the maximum duration of DosFindNotifyFirst before 
returning to the function caller. 


If ERROR (AX not = 0) 
AX = Error Code: 


* ERROR NO MORE SEARCH HANDLES - too many search handles are 
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currently in use by the process. 


* ERROR PATH NOT FOUND ~- the drive letter is invalid, there 
are too many .., Chere are wildcards present before the 
last component, or a component of the directory path is 
not present. 


* ERROR_INVALID PARAMETER - the search attribute is invalid 
or a change count of zero is specified. 


* ERROR_BUFFER OVERFLOW - the specitied buffer is too small 
Lo support a single entry. 


*  ERROR_FINDNOTIFY TIMEOUT - the timeout expired without the 
requested number of changes occurring. 

* ERROR VOLUME CHANGED - the volume changed in the drive 
specified PathSpec. 


7 Device-driver/device-manager errors listed “------ ----- 
Sa eee ae een " on page ---. 


The find notify API allow a desktop to be informed of changes in a 
directory in order to provide an up-to-date view of the directory. 
Changes consist of changes to names within a directory (file 
create, file delete, file/directory rename, directory create, 
directory removal) plus operations that change a file attribute. 
Those operations are SetFileMode, SetFilelInfo, and SetPathInfo for 
both standard attributes and extended attributes. Changes that 
occur to PathSpec in between calls to DosfindNotifyFirst and 
DosFindNotifyNext or DosFindNotifyNext and DosFindNotifyNext wil! 
be included in the ChangeCount. 


Changes to date and time and size will NOT be reported for each 
read or write, but will instead be reported when a file is closed 
cr committed. 


Volume changes will on the drive specified in PathSpec will be 
detected. Any thread waiting on a path on that drive will be 
returned with an error code. The ChangeCount will be valid and 
the corresponding information will be stored in ResultBuf. No 
DirHandle will be allocated and no call to DosFindNotifyClose 
should be issued. 


DosFindNotifyFirst will block until either the timeout specified 
has elapsed or until the specified number of changes has been 
found. 
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2.1.8.6.20 DosFindNotifyNext - Return directory: change information. 
Purpose Return directory change information. 
Format Calling Sequence: 
EXTRN DosFindNot ifyNext :FAR 
PUSH WORD DirHandle ; Directory handle 
PUSH@ OTHEK Result Buf 3; Result. bufter 
PUSH WORD ResultS8uflen ; Result buffer length 
PUSHB WORD = ChangeCount ; #@ of changes required 
PUSH DWORD TimeOut ; Duration of call 
CALL DosFindNotifyNext 
Whece DirHandie is the handle (previously returned by DOS) associated 
with a previous DosFindNotityFirst or DosFindNotifyNext function 
call. 
ResultBuf is where the FSD returns the results of the qualified 
directory search. The information returned is guaranteed to be at 
least as accurate as the most recent DosClose or DosBufResetc. 
ResultBufLen is the length of ResultBuf. 
ChangeCount is the number of changes required to directories or 
files that match the PathSpec target and Attribute specified 
during a related, previous DosFindNotifyPirst. The file system 
uses this field to return the number of changes that actually 
occurred since the present DosFindNolifyNext was issued. 
TimeOut is the maximum duration of DosFindNotifyFirst before 
returning to the function caller. 
Returns: IF ERROR (AX nat = 0) 
AX = Error Code: 
. ERROR_INVALID HANDLE - the specified handle is not in use. 
* ERROR INVALID PARAMETER - 4 change count of zero is 
specified. 
. ERROR BUFFER OVERFLOW - the specified buffer {1s too smal) 
Lo support a single entry. 
. ERROR FINDNOTIPY TIM’ OUT the tameout expired without the 
requested number of chanyes occurring. 
* ERROR VOLUME CHANGED - the volume changed in the drive 
specified in PathSpec. 
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3 ERROR_FINDNOTIFY HANDLE _IN_USE - another thread is using 
the specified DirHandle. 


*  ERROR_FPiNDNOTIFY_HANDLE CLOSED - a DosFindNotifyClose has 
been issued on the DirHandle. 


bg Device-driver/device-manager errors listed “------ ----- 
Reem meme aoee—" On page --~. 


Remarks DosFindNotifyNext will block until either the timeout specified 
has elapsed or until the specified number of changes has been 
found. 
Volume changes will on the drive specified in PathSpec will be 
detected. Any thread waiting on a path on that drive will be 
returned with an error code. The ChangeCount will be valid and 
the corresponding information will be stored in ResultBuf. If ne 
thread is waiting, the DirHandle assoctated with the drive will be 
marked invalid and the next call using the DirHandie will be 
returned immediately with an error code. A DosFindNotifyClose 
should be issued by the user. 
Only one thread will be able to sleep on a DirHandle at one time. 
For example, a DosFindNotifyNext cannot be issued by one thread 
while another thread has issued a DosFindNotifyNext on the sam: 
DirHandle. 
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2.1.8.6.21 DosFsAttach ~ Creates and destroys FSD connections.: ReturnCode = 0 if no error 
"Purpose Attaches or detaches drive to/from a remote’ FSD, or a ReturnCode = Error cade if error 
* pseudo~character device name to/from a local or remote FSD 
*  ERROR_INVALID DRIVE - the drive specified in DeviceName is 
Format Calling Sequence: illegal. 
* ERROR_INVALID_PATH - the pseudodevice specified in DeviceName 
EXTRN DosFsAtt ach:FAR is illegal. 
PUSH@ ASCIIZ DeviceName ; Device name or ‘d:‘ : * _ERROR_INVALID FSD NAME ~- the FSD name specified is not found. 
PUSH@ ASCIIZ FSDName 3 FSD name 
PUSH® OTHER Dat aBuffer ¢ Attach argument data | bd ERROR_INVALID LEVEL - the value of OpFlag is invalid. 
PUSH WORD DateButferLen ; Buffer length c 
PUSH WORD Opt lag 3 Attach or detach I * ERROR_NOT ENOUGH MEMORY - cannot create OS/2 internal data 
PUSH ODWORD O ¢ Reserved {must be zero} | structures. ‘ 


CALL DosksAttach 


Remarks The redirection of drive letters representing local drives is not 


Where DeviceName points to either the drive letter followed by a colon, supported. 
or points to a pseudo-character device name. If DeviceName is a 
drive, it is am ASCIIZ string having the form of drive letter FSDs that wish to establish open connections that are not attached 
followed by a colon. 1€ an attach is successful, all requests to to a name in the system’s name space, for such purposes as 
thet drive are routed to the specified FSD. If a detach is optimizing UNC connections or establishing access cights, must use 
successful, the drive will disappear from the system’s name space. an DosFsCrl function to do so. DosFsAttach only creates 


attachments to drives or devices in the system’s name space. 
lf DeviceName is a pseudo-character device name (i.e., single file 


device), its format is that of an ASCI1Z string in the format of See description of pseudo-character devices. 
an OS/2 filename in a subdirectory called \DEV\. All requeats to 

that name are routed to the specifted FSD after a successful 

attach. A successful detach removes the name from the aysten's 

name space. 


FSOName is the ASCIIZ name of the remote FSD to attach to or 
detach from DeviceName. 


DataBuffer points to the user-supplied FSD argument data area. 
| The meaning of the data is specific to the FSD. The Databuffer 
" will contain contiguous asciiz strings, with the first word of the 
\ buffer containing the number of asciiz strings. 

DataBufferlLen is the byte length of the data buffer. 

OpFlag defines the type of operation to be performed. 

. Attach = 0 


* Detach = 1 


Returns: AX = 0 
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2.1.8.6.22 DostsCrl - File System Control: 


Purpose Allows an extended standard interface between an application and 
an FSD. 

Format Calling Sequence: 
EXTRN DosFsCtl:FAR 
PUSH@ OTHER DataArea ; Datla area 
PUSH WORD DataLengthMax ; Max length of data area to be return 
PUSH @WORD DataLength ; In: Length of data returned from FSD 

7 Out: Length of data returned by FSD 
PUSH@ OTHER Parml.ist ¢ Parameter list 
PUSH WORD ParmLengthMax ; Max length of Parameter list passed 
PUSH @WORD ParmLength ; In: Length of Parameter list sent by 
¢ Out: Lenght of Parameter returned by FSD 

PUSH WORD Funct sonCode z Function code 
PUSH@ ASCIIZ RouteName 3 Path or FSD name 
PUSH WORD Filetiandle : Flle handle 
PUSH WORD RouteMethod 3 Method for routing. 
PUSH DWORD 0O ; Reserved {must be zero} 
CAL. DosFscrl 

Where DataArea {1s a data area. 
DataLengthMax is Che maximum length of the data to be returned by 
the FSD in DataArea. DataLength may be longer than this on input, 
but not on output. 
DataLength is the length in bytes of data returned in DataArea. 
On input, it is the length of data being sent, and on output is 
the length of the data that was returned by the FSD. I€ 
ERROR BUFFER_OVERFLOW is returned from the call, then it is the 
size of the buffer required to hold the data returned by the FSD. 
Parml.ist is a command specific parameter list. 
ParmLengthMax is the maximum length in bytes of the data to he 
returned by the FSD inParcmList. ParmLength may be longer than 
this on input, but not on output. 
ParmLength jis, on input, the lenyth of parameters passed in by 
the application, and on return, it ds the length of parameters 
ceturned by the FSD. If ERROR BUFFER OVERFLOW is returned from 
the call, thes st contains the size of buffer required to hold the 
parameters returned by the FSD. No other data is returned in this 
case. 
FunctionCode is the tilesystem-specific function code. Function 

2.0 Functional Characteristics 155 


t 
¢ 

o FSD 
application 
4 


Microsoft Confidential 
OS/2 1.2 IFS Patent Documentation 


codes between 0x0000 and Ox7FFF are reserved for use by 05/2. For 
remote FSDs, there are two kinds of possible FsCtl calls: 


ones that are handled locally, 
ones that are exported across the network. 


indicates to 
The cange of 


if bit 0x4000 is set in the function code, then this 
the remote FSD that the function should be exported. 
function codes are split up as follows: 


0x0000 - Ox7FFF reserved for definition by OS/2 


Ox8000 - OQx8FFF FSD defined fsctl functions handled by 
local FSD. 
t 
OxCO00 - OxFFFF FSD defined fscti 
server 


functions exported tu 


® FunctionCode = 0x000) ts used to obtain new error code 
information from the FSD. 


" FunctionCode = 0x0002 is used to query the FSD for the maximum 
size of individual EAs and the maximum size of the full EA 
list that it supports. The information is returned in 
DataArea in the following format: 


EASizeBufStruc [| 
unsigned short easb MaxEASize /* Max. size of an in 
EA supported */ 
unsigned long easb_MaxEAListSize /* Max. full EA list 
supported */ 
) 


RouteName is the ASCIIZ name of the FSD, or the pathname of a file 
or directory the operation should apply to. 


FileHandle is the file or device specific handle. 
RouteMethod selects how the request will be routed. 
*  RouteMethod = 1: FileHandle directs routing. 


be NUL pointer {O0L). 
receive the request. 


RouteName must 
The FSD associated with the handle wiil 


*  RouteMethod = 2: RouteMethod refers toa pathname, which 
directs routing. FileHandle must be ~1. The FSD associated 
with the drive the pathname refers to at the time of Lhe 
request will receive the request. The pathname need not refer 
to a file or directory which actually exists, only to a drive 


which does. A relative pathname may be used, it will be 
processed like any other pathname. 
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* RouteMethod = 3: RouteMethod refers to an FSD name, which 


directs routing. FileHandle must be -1. The named FSD will 
receive the request. 


Returns: IF ERROR (AX not = 0) 


AX = Error Code: 


Remarks none 


ERROR_1INVALID_ FUNCTION - the specified function is illegal 
for the particular category and handle. 


ERROR INVALID CATEGORY - the specified category is illegal 
for the particulac function and handle. 


ERROR INVALID PAKAMETER - the filehandle != -1 when the 
routemethod == 2? = of the routename '!=x Q when the 
routemethod -- 1. 


ERROR INVALID HANDLE - the specified file handle is not in 
use or is attached to a physical device. 


ERROR _INVALID FSD NAME - the specified FSDName is not 
responsible for managing the specifed file handle. 


ERROR_INVALID LEVEL ~- invalid route method. 
ERROR_INTERRUPT - the current thread received a signal. 


ERROR BUFFER OVERFLOW - either DataArea orf ParmList are 
not big enough to hold the data that che FSD is returning. 
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2.1.8.6.23 DosMkDir - Make Subdirectory: 


Purpose Creates the specified directory. 
Format Calling Sequence: 
EXTRN DosMkDir:FAR 
PUSH@ ASCIIZ DirName ; New directory name 
PUSH DWORD 90 ; Reserved (must be zero) 
CALL Dos#kDir 
EXTRN DosMkDir2:FAR , 
PUSH@ ASCIIZ DirName 7 New directory name 
PUSH@ OTHER EABuf ¢ Extended attribute buffer 
PUSH DWORD 0 ¢ Reserved {must be zerca) 
CALL DosMkDir2 
Where DirName is the ASCIIZ directory path name. 
EABuf contains, on input, an EAOP structure. fpGEAList is 
ignored. fpFEAList points to a data area where the relevant FEA 
list ia to be found. offf€rror is ignored. 
On output, fpGEAList is unchanged. fpFEAList is unchanged as is 
the area pointed to by fpFEAList. If an error occurred during the 
set, offf€rror will be the offset of the FEA where the error 
occured. The API return code will be the error code corresponding 
to the condition generating the error. If no error occurred, 
offErrorc is undefined. 
If EABUf is 0x00000000, Chen no extended attributes are defined 
for the directory. 
Returns: IF ERROR (AX not = 0) 
AX = Error Code: 
* ERROR PATH NOT FOUND - the drive letter is invalid, there 
are too many .., there are wildcards present, or a 
component of the directory path is not present. 
® ERROR_FILENAME EXCED RANGE - the path specified is 
unacceptable to the FSD managing the volume. 
*  ERROR_ACCESS DENIED ~- the directory already exists or a 
file with this name exists. 
2.0 Functional Characteristics 158 


00084 


eV Sve SLY O dS 


Hemarks 


Microsoft Confidential 
OS/2 1.2 IFS Patent Documentation 


® Device-driver/device-manager errors listed "-----~ ---- - 
Tease Senee eeoew “ on page ---. 


"  ERROR_INVALID_EA NAME - there is an illegal character in 
an EA name. The offError field points to the offending 
FEA. 


* ERROR_EA LIST INCONSISTENT - the cbhList does not match the 
sum of the tengths of the FEA structures. 


* ERROR EA_VALUE UNSUPPORTABLE - the FSD detects an error in 
the value portion of an EA. The offError field points to 
the offending FEA. 


bt any member of the directory path does not exist, then the 
directory path ts mot created. On return, a new directory is 
created at the end of the specified path. 


DosQSysinfo must be used by an application to detemine the 
maximum path length supported by OS/2. The returned value should 
be used to dynamically allocate buffers that are to be used to 
store paths. This will ensure chat applications funct lon 
correctly (wrt path lengths) for future versions of OS/2. The 
path length includes the drive specifier (1.e. d:}, the leading 
*\’ and the trailing NUL. 
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2.1.8.6.24 DosMove ~ Move a File or a Subdirectory: 


Purpose Moves the specified file or subdirectory. 
Format Calling Sequence: 
EXTRN DosMove:FAR 
PUSH@ ASCITZ OldPathName ; Old path name 
PUSH@ ASCIIZ NewPathName ; New path name 
PUSH DWORD 0 ¢ Reserved (must be zero) 
CALL DosMove 
Where ’ 
OldPathName is the old ASCII2Z path name of che file or 
subdirectory to be moved. 
NewPathName is the new ASCIIZ path name of the file oz 
subdirectory to be moved. 
Returns: IF ERROR (AX not = 0) 
AX = Error Code: 
* ERROR_PATH_NOT FOUND - the drive letter is invalid, there 
are too many .., there are wildcards present, or a 
component of the directory path is not present. 
*  BRROR_FILENAME_EXCED RANGE - the path specified is 
unacceptable to the FSD managing the volume. 
* ERROR_SHARING_VIOLATION - the OldPathName is currently 
open. 
*  PRROR_FILE NOT FOUND ~ the OldPathName is not present 
* ERROR_NOT SAME DEVICE - the OldPathName and NewPathName 
are on different physical devices. 
* ERROR_ACCESS DENIED -  NewPathName already = exists, 
OldPathName is a character device, orc OldPathName is a 
pseudocharacter device. 
*  PRROR_CIRCULARITY REQUESTED - the OldPathName is = an 
ancestor of the NewPathName. 
* ERROR_DIRECTORY_IN_CDS - the OldPathName is the current 
directory of a process. 
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*  ERROK SHARING BUFFER_EXCEEDED - there is not enough memory 
to hold sharing information. 


« Device-driver/device-manager errors listed “------ +--~- 
Sree oo ee “ on page ---. 


Remarks The directory paths need not be the same, allowing a file or 
subdirectory to be moved to another directory and renamed in the 
process. 

Wildcard characters are not allowed in the source or destination 
name. 

File systems will reject requests that move a parent directory to 
one of {ts subdirectories in order ta avoid a loop in the 
directory tree. A subdirectory cannot be both a descendent and an 
ancestor of the same directory. 

An attempt to move the current directory or any of its ancestors 
for the current or any other process will fail and cause the 
operation to terminate. 

An attempt to move the current directory for any process will fail 
and cause the operation to terminate. 

Read~only files in the target path are not replaced. 

DosQSysInfo must be used by an application to detemine Che 

maximum path length supported by OS/2. The returned value should 
be used to dynamically allocate buffers that are to be used to 
store paths. This will ensure that applications function 
correctly (wrt path lengths) for future versions of 0S/2. The 
path length Includes the drive specifier (i.e. d:), the leading 
*\' and the trailing NUL. 

DosMove will move the source’s attributes (date of creation, time 
of creation, ...) to the target. 
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2.1.8.6.25 DosNewSize - Change Flie’s Size: 


Purpose 


Format 


Where 


Returns: 


Remacks 


2.0 Functional Characteristics 


Changes a file’s logical (£OD) size. 


Calling Sequence: 


EXTRN DosNewSize:FAR 
PUSH WORD FileHandie ; File handle 


PUSH DWORD FileSize ¢ File’s new size 
CALL DosNewSize 


FileHandle is the handle of the file whose size is being changed. 
FileSize is the file's new size in bytes. 
IF ERROR (AX not = 0) 
AX = Error Code: 


*  ERROR_DISK_ FULL - there is not enough roomto grow the 
file. 


* ERROR_INVALID PARAMETER - the size is negative. 


* ERROR INVALID HANDLE - the handle is not in use or is 
attached to a physical device. 


* ERROR_ACCESS DENIED - this handle is opened read-only. 


*  ERROR_LOCK VIOLATION - the region of file growth overlaps 
a locked region. 


ad Device-driver/device-manager errors listed %------ ----- 


scene omnes awme *" on page ---. 


The file hanlde must be opened for read/write or write-only 
access. 


The value of new bytes in the extended file is undefined. 


The file system will make a reasonable attempt to allocate the new 
size in a contiguous (or nearly contiguous) space on the media. 
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2.1.8.6.26 DosOpen ~ Open a File: 


Purpose Creates the specified file (if necessary), and opens it. 
Format Calling Sequence: 
EXTRN DosOpen: FAR 
PUSH® ASCIIZ FileName : File path name 
PUSH@ WORD Fi leHandle 7; New file’s handle e 
PUSHE WORD Act ionTaken i; Action taken » 
PUSH DWORD FileSize ; File primary allocation " 
PUSH WORD FileAttribute ; File Attribute * 
PUSH WORD OpenF lag 3; Open function type 
PUSH WORD OpenMode ; Open mode of the file 
PUSH DWORD 6 i; Reserved (must be zero) 
CALL DosOpen 
EXTRN DosOpen2:FAR 
PUSH@ ASC112 FileName : File path name 
PUSH® WORD FileHandle ; New file’s handle 
PUStid WORD Act jonTaken 3 Action taken 
PUSH DWORD FileSize 3 File primary allocation 
PUSH WORD FileAttribute ; File Attribute 
PUSH WORD OpenFlag 3 Open function type 
PUSH DWORD OpenMode ; Open mode of the file 
PUSH@ OTHER EABuf 7; EA butfer 
PUSH DWORD O ; Reserved (must be zero) 
CALL DosOpen2 
Where 
FileName ts the ASCEIIZ path name of che file or device name to be 
opened. a 
: 
FileHandle 1s where the system returns the file handle. \ 
1 
ActionTaken is where the system returns a description of the 
action taken as a result of the DosOpen function call. 
‘ Ox0001 file existed 
* O0x0002 file was created 
: Ox0003 file was replaced 
FileSize is the new file’s logical size (EOD) in bytes. 
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FileAttribute is the file attribute. Refer to DosQFileMode or 
DosSetFileMode for a description of FileAttribute. 


OpenFlag specifies the action to be taken depending on whether or 
mot the file exists. 


* OpenFlag specification: 


Low Order Byte 


moo MKKN action taken iff file exists 

~--- 0000 fail 

---- 0001 open file 

---- 0010 replace file 

XRMM oon action taken if file 
doe'sn't exist 

0000 ---- fail 

000i ---- create file 


OpenMode i{s Che open mode and consists of the following bit 
fields. They are the: 


* Inheritance flag 

* Write-through flag 
* Fail-errors flag 

a Sharing mode fleld 
* Access field 

* Reserved bit fields 


The bit field mapping is shown as follows: 


$2237 1 
Open Mode 54321096765 43210 
bits DWFCRLLLISSSRAAA 
D Direct Open 


The file is opened as follows: 


If D = 0; FileName represents a file to be 
opened in the normal way. 

If D = 1; FileName is "<Drive>:* and 
represents a mounted disk or diskette 
volume to be opened for direct access. 
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File Write-through | 
The tile is opened as follows: 


lf We: Of; Weites to the file may be run 
through the DOS buffer cache. 
If W- 1; Writes to the file may go 
through the DOS buffer 
cache but seclors 
will be written {actual file 
1/0 completed) before a 
synchronous write call cerucos. 
This state of the file defines 
il a8 a synchronous tile. 


NUTE that thts is a mandatory bit in that the data MUST be 
written out to the medium for synchronous write 
operations. This bit is not inherited by child processes. 


Inheritance Flag 


tf 1 = OF; Fille handle is inherited by a 
Spawned process resulting 
from a DosExecPgm call. 

1f 1 = 1; File handle is private to the 
current process. 


This bit is not inherited by child processes. 
Fail-Errors 
Media 1/0 errors will be nandiecd as follows: 


it F = O; reported through the system 
critical error handler. 

If F - 1; ceported directly to the 
caller via return code. 


This bit is not inherited by child processes. Media 1/0 
errors generated through an LoCt] Category 8 function, 
always gel ceported directly to the caller via return 
code. The Fail-Errors functionality applies only to 
non-LloCtl handle-based type {1:le 1/0 calls. 


Cache/No-Cache 


The {ile is opened as follows; 

If c = UO; 1/0 to the file need not be done s 
through the disk driver cache. 

If C = i: Tt is advisable for the disk driver 
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to cache the data in I/O operations 
on this tile. 


This bit ts an ADVISORY bit, and is used to advise FSDs 
and device drivers on whether it is worth caching the data 
or not. This bit, like the write-through bit, is a 
per-handle bit. It is not inherited by child processes. 


R Reserved and must-be-zero field 
L Locality of reference 


The locality-ot-reterence is advisory information about 
how the application will access the file. 


If L == 00; no locality known 

If L == 01; mainly sequential access 
If L == 10; mainly random access 

If L == 11]; random with some locality 


Ss Sharing Mode 


The file sharing mode field defines what operations other 
processes may perform on the file. 


If S$ = 001; Deny Read/Write access 

Tf S = 010; Deny Write access 

If S = 011; Deny Read access 

If S = 100; Deny Neither Read or 
Write access (Deny None) 


Any other value is invalid. 
A Access Mode 
The file access is assigned as follows: 
If A = 000; Read-only access 
If A = 001; Write-only access 
If A = 010; Read/Write access 


Any other value is invalid. 


Any other combinations are invalid. 


When opening a file, it is important to inform OS/2 what 
operations other processes may perform on this file (shariny 
mode}. [If it is permissible for other processes to continue to 
read this file while your process is operating on the file, you 
should specify Deny Write, which inhibits writing by othe: 


2.0 Functional Characteristics 166 


00088 


oV SVE SIP O da 


Microsoft Confidential 
OS/2 1.2 IFS Patent Documentation 


processes, but allows reading by them. 


Similarly, it is important to specify what operations your process 
will perform (access mode). The Read/Write access mode causes the 
open request to fail if another process has the file opened with 
any sharing mode other than deny none. If however, all you 
intended to do is read from the file, your open will not succeed 
unless all other processes have specified deny none or deny write 
(checefore increasing access to the file}. File sharing requires 
cooperation of both sharing processes. This cooperation is 
communicated through the sharing and access mode. 


EABUf contains, on input, an EAOP structure. fpGEAList is 
ignored. FpFEAList points to a data area where the relevant FEA 
list is to be found. offError is ignored. 


On outpul, fpGEAList is unchanged. tpFEAList is unchanged as is 
the area pointed to by fpFEAList. If an error accurred during the 
set, offError will be the offset of the FEA where the error 
occured. The API return code will be the error code corresponding 
to the condition generating the error. If no error occurred, 
offError is undefined. 


lf EABuf is 0x00000000, then no extended attributes are defined 
for the tile. 


If Extended Attributes are not to be defined or modified, then 
the pointer, EABuf, must be set to null. 


Returns: IF ERROR (AX not = 0) 
AX = Error Code: 
* ERROR _INVALID_PARAMETER - the OpenFlag value is invalid, 
the OpenMode value is invalid, the OpenFlag/OpenMode 
values are incompatible, or the size specified in a 
replace/create operation is negative. 
s ERROR INVALID ACCESS - the access mode field is invalid. 
* ERROR ACCESS DENIED - the = attributes specified are 
invalid, the file is read only and OpenMode requests a 
write access, or the FileName points to a directory. 
" ERROR OPEN FAILED - the combination of OpenFlag and state 
of the file results in a failed operation. 
. ERROR DISK FULL ~- there is not enough room on the media to 
create the file with the specified size. 
® ERROR TOO MANY OPEN FILES - there are too many files open 
by either the system or the process. 
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* ERROR_FILE_NOT_FOUND - the last component of the file name 
is not present on the media. 


* ERROR_PATH_NOT_FOUND - a component of the directory path 
is not present. 


* ERROR_SHARING BUFFER_EXCEEDED - there is not enough memory 
to hold sharing information. 


*  ERROR_SHARING_VIOLATION - the FileName is currently open. 


* ERROR_FILENAME EXCED RANGE - the path specified = is 
unacceptable to the FSD managing the volume. 


* Device-driver/device-manager errors listed "----~- ----- 
See Saeet SaaS "on pagg ~--. 


*  ERROR_INVALID_EA_NAME - Chere is an illegal character in 
an EA mame. The offError field points to the offending 
FEA. 


*  ERROR_EA LIST_INCONSISTENT - the cbhList does not match the 
sum of the lengths of the FEA structures. 


*  ERROR_BA_VALUE UNSUPPORTABLE - the FSD detects an error in 
the value portion of an EA. The offfrror field points to 
the offending FEA. 


*  ERROR_DEVICE IN_USE - the device is in use by another 
application. 


The read/write pointer is set at the first byte of the file. The 
read/write pointer can be changed thraugh function DosChgFilePtr. 


The file’s date and time can he obtained through function 
DosOF ileinfo. 


The file’s date and time can be set through -— function 
DosSetFileInfo, and its attribute can be obtained through function 
DosQFileMode. 


The FileSize parameter affects the size of the file onty when it 
is created or replaced. If an existing file is simply opened, 
FileSize is ignored. This is a recommended size for the file. If 
allocation of the full size fails, the open may still succeed. 


The Direct Open bit parameter is the “Direct 1/0 flag". It 
provides an access mechanism to an entire disk or diskette volume 
independent of the file system. This mode of opening the volume 
currently mounted on the drive, is used to return a handle to the 
caller which represents the logical volume as a single file. In 
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order to block other processes from accessing the logical volume, 
the caller must also issue a DosbevioCrl] Category 8 sub-function 
Q, which requires the file handle for the logical volume returned 
by DosOpen. 


The tile handle state bits can be set by che DosOpen and 
DosSetFuState function calls. An application may query the file 
handle state bits as well as the rest of the Open Mode field, by 
using the DosQFHandState function call. 


The retucned file handle must be used for subsequent input and 
gutput to the file. 


The value of new bytes in the extended file is undefined. 


The file system must make a reasonable attempt to allocate the new 
size in a contiguous (or nearly continguous}) area on the media. 
Extended attributes that indicate required contiguity may reject 
the call if unable to allocate contlguous space. 


The extended attributes will be set for creation of a new file, 
ceplacement of an existing file, and truncation of an exiating 
file. No attributes are set for a normal open. 


FileAttribute cannot be set to Volume Label. Volume labels 
cannot be opened. 


Notes: 


}. A multitasking system must be able to use files and their 
existence as semaphores. This function call may be used as a 
test-and-set semaphore when used to create a new file. 


2. When a file is closed, any sharing restrictions placed on it 
by the open are removed. 


3. The tile read-only attribute can be set by using the 
DosSetFileMode function call or the OS/2 ATTRIB command. 


4. {ft the file is inherited by a spawned process, all sharing and 
access restrictions are also inherited. 


5. If an open file handle ts duplicated by function call} 
DusDupHsndle, all sharing and access restrictions are also 
duplicated. 


Sharing Modes 


Deny Read/Write Mode 
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If a file is successfully opened in Deny Read/Write mode, access 
to the file is exclusive. A file currently open in this mode 
cannot be opened again in any sharing mode by any process 
(including the current process) until che file is closed. 


Deny Write Mode 


A fille successfully opened in Deny Write sharing made, prevents 
any other write access opens to the file (A = 001 or 010) until 
the file is closed. An attempt to open a file in Deny Write mode 
is unsuccessful if the file is currently open with a write access. 


Deny Read Mode 


A file successfully opened in Deny Read sharing mode, prevents any 
other read sharing access opens to the file (A = 000 or 010) unci) 
the file is closed. An attempt to open a file in Deny Read 
sharing mode is unsuccessful if the file is currently open with a 
read access. 


Deny None Mode 


A file successfully opened in Deny None mode, places no 
restrictions on the read/write accessibility of the file. 


Named Pipe Considerations Opens the client end of a pipe by name and 


returns a handle. The pipe must be in listen state for the open 
to succeed; otherwise the open fails with PIPE BUSY (this happens, 
for example, if all instances of the pipe are already open, if the 
pipe is closed but not yet disconnected by the serving end, or if 
no DosConnectNmPipe has been issued against the pipe since it was 
last disconnected). Once a given instance has been opened by a 
client that same instance cannot be opened by another client at 
the same time (i.e., pipes can only be two-ended at present); the 
opening process can of course dup the open handle as many times as 
desired. The access and sharing modes specified on the open must 
be consistent with those specified on the DosMakeNmPipe. Pipes 
are always opened with the pipe-specific states set to B « 0O 
(blocking reads/writes), RR = 00 (read as byte stream). The 
client can change these modes via DosSetPHandState if desired. 
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2.1.8.6.27 DosQCurDie - Query Current Directory: 


Purpose Gets the full path name of the current directory foc the 
requesting process for the specified drive. 


Format Calling Sequence: 
EXTRN DosQCurDir:FAR 
PUSH WORD DriveNumber 
PUSH@ OTHER DicPath 


PUSH@® WORD DirPathLen 
CALL DosQCurDir 


Drive number 
Directory path buffer 
Directory path buffer length 


Where 
DetveNumber is the derive number (O=default, 125A, ... ). 
DirPath is where the system returns the full directory path name. 
DirPathLen is the length of the DirPath buffer. 
Returns: JF ERROR {AX not = 0) 
AX = Ecrorc Code: 
¢ ERROR_INVALID DRIVE - the specified drive is invalid. 


* ERROR BUFFER_OVERFLOW - the current directory is too long 
to fit into the specified directory. 


« Device-driver/device-manager errors listed "%--<---- ----+ 
SSS. cSe ee ee “ on page -~--. 


Remarks The drive letter is not part of the returned string. The string 
does not begin with a backslash and is terminated by a byte 
containing 0x00. 


The system returns the length of the returned DirPath string {not 
including the 0x00 terminating null byte) in DirPathLen. 


In the case where the DirPath buffer is of insufficient length to 
hold the current directory path string, the system returns Che 
required length {in bytes) for DicPath in DirPathLen. 


DosQSysInfo must be used by an application to detemine the 
maximum path length supported by OS/2. The rcetucned value should 
be used to dynamically allocate buffers that are to be used ta 
store paths. This will ensure that applications function 
correctly (wrt path lengths) for future verstons of OS/2. The 
path length includes the drive specifier {i.e. di), the leading 
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2.1.8.6.28 BosQCurDisk - Query Current Disk: 


Purpose Determine the current default drive tor the requesting process. 
Format Calling Sequence: 
EXTRN DosQCucDisk:FAK 
PUSH® WORD DriveNumber 3 Default drive number 
PUSH@ DWORD LogicalDriveMap ; Drive-map atea 
CALL DosQCurDisk 
Where 
DriveNumber is where the system returns the number of the default 
drive (1+A, 2+B, ... ) 
LogicalDriveMap is a bit map (stored in the low-order portion of 
the 32-bit double word area) in which the system returns the 
mapping of the togical drives. Logical Drives A-Z have a 
one-Co-one mapping with the bit positions O-25 of the map. 
« If bit value = 0, the logical drive does not exist 
" if bit value = 1, the logical drive exists 
Returns: No error returns are defined for this API. 
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2.1.8.6.29 DosQFHandState - Query File Handle State: 
Purpose Query the state of the specitied file. 


Format Calling Sequence: 


EXTRN DosQFHandState:FAR 
PUSH WORD Filellandle 3 File handle 
PUSH@ WORD FileHandleState : File handle state 
CALL DosQFuHandState 
Whe re 
FileHandle is the handle of the file to be queried. 


FileHandleState is the file handle state and consists of 
following bit fields. They are the: 


« Inheritance flag 

* Write-through flag 

& Fail-errors flag 

* Sharing mode field 

= Access field 

= Reserved bit fields 

The bit E£ield mapping is shown as follows: 


Open Mode bits 


D Direct Open 
The file is opened as follows: 


If D = QO; Pathname represents a file 
opened in the normal way. 

If D = 1; Pathname is "<Drive>:" and 
represents a mounted disk or diskette 
volume to opened for direct access. 


I Inheritance Flag 
If 1 = 0; File handle is inherited by a 


spawned process resulting 
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from a DosExecPqm call. 
If 1 = 1; File handle is private to the 
current process. 


This bit is not inherited by child processes. 
Ww File Write-through 
The file is opened as follows: 


If W «= 0; Writes to the file may be run 
through the DOS buffer cache. 
Weites to the file may go 
through the POS buffer 

cache but sectors 

will be written (actual file 
1/O completed) before a 
synchronous write call returns. 
This state of the file defines 
it as a synchronous file. 


If We i; 


NOTE that 
written 
operations. 


this is a mandatory bit in that the data MUST be 
out to the medium for synchronous write 
This bit is not inherited by child processes. 


F Fail-Errors 
Media 1/0 errors will be handled as ftollows: 


If F = 0; ceported through the system 


erleical error handler. 


If F = 1; reported directly to the 

'" caller via return code. 
This bit is not inherited by child processes. Media 1/0 
errors generated through an loCti Category 8 function, 
always get reported directly to the caller via return 
code. The Fail-Errors functionality applies only to 


non-loCt)] handle-based type file 1/0 calls. 


Cc Cache/No-Cache 


The file 1s opened as follows: 

If c 4 O; 1/0 to the file need not be done 
through the disk driver cache. 

If Cc => 1; It ts advisable for the disk driver 
to cache the data in 1/0 operations 
on this file. 


This bit is an ADVISORY bit, and is used to advise 
and device drivers on whether it is worth caching the data 
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Named Pipe Considerations As 


defined by DosMakeNmPipe (serving end), DosOpen (client end), or 
the last DosSetFHandState. 


IF ERROR (AX not = 0) 
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Or not. This 
per-handle bit. 


bit, like the write-through bit, isa 
It is not inherited by child processes. 


These bits are reserved and should be set to the values 
returned by DosQFHandState in these positions. 


Sharing Mode 


The file sharing mode field defines what 


other processes may perform on the file. 


operations 


001; Deny Read/Write access 

010; Deny Write access 

011; Deny Read access 

100; Deny Neither Read or 
Write access (Deny None) 


= 
> 
wr 
ae F 


Any other value is invalid. 

Access Mode 

The file access is assigned as follows: 
If A = 000; Read-only access 

If A = 001; Write-only access 

If A= 010; Read/Write access 


Any other value is invalid. 
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AX = Error Code: 


ERROR_INVALID HANDLE - the handle is not in use or is 


attached to a physical device. 


defined by OS/2. D «= O. Other bits as 
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2.1.8.6.30 DosQFilelnfo - Query a File’s Information: 
Purpose Returns information for a specific file. 
Format Calling Sequence: 
EXTRN DosQFi leInto:FAR 
PUSH WORD Filetlandle 
PUSH WORD FilelinfoLlevel 
PUSH@® OTHER Fileinfobul 


PUSH WORD FilelInfaBulSize 
CALL DosQFileinfo 


File handle 

File data required 
File data buffer 

File data buffer size 


*, Se Se» %e 


Where FileHandJe is the file handle. 


FileInfoLeve! 1s the Jevel of tile information required. 


File information, where applicable, 1s at least as accurate as the 


most recent DasClose, DosBufReset, or DosSetkileinfo. 


Level 0x0001 information is returned in the following format: 


struct { 
unsigned short dateCreate; 
unsigned short’ CimeCreate; 
unsigned short dateAccess; 
unsigned short timeAcceas; 
unsigned short dateWrite; 
unsigned short timeWrite; 
long cbEOF; 
long cbhAli loc; 
unsigned short attr: 


Level Qx0002 simply adds cbList to level 0x0001, returning 
Structuce in the following format: 


2.0 Functional Characteristics 


177 


+ » © & © 


> 


~+ + + 


Microsoft Confidential 
OS/2 1.2 IFS Patent Documentation 


Struct { 
unsigned short dateCreate; 
unsigned short timeCreate; 
unsigned short dateAccess; 
unsigned short t imeAccess; 
unsigned short dateWrite; 
unsigned short timeWrite; 
long cbEOF; 
long cbAlloc; 
unsigned short § attr; 
unsigned long cbList; 


Level 0x0003 file information , returns a subset of the EA 
information for the file. On input, FilelInfoBuf is an EAOP 
structure above. fpGEAList points to a GEA List defining the 
attribute names whose values will be returned. fpFEALiat points 
to a data area where the relevant FEA list will be returned. The 
length field of this FEA list is valid, giving the size of the FEA 
list buffer. offError points to the offending GEA entry in case 
of error. 


On output, FileinfoBuf is unchanged. The buffer pointed to by 
fpFEAList is filled in with the returned information. 


If the buffer fpFEAList points to isn’t large enough to hold the 
returned information (ie ERROR BUFFER OVERFLOW) cbList will stilt 
be valid, assuming there’s at least enough space for it. Its 
value will be the size of the entire EA set for the file, even 
though only a subset of attributes was requested. 


***THE FOLLOWING UNPUBLISHED FUNCTION WILL GO AWAY IN FUTURE **ee« 
““*RELEASES AND SHOULD BE UNPUBLISHED®** 


Level 0x0004 file information returns all EA info for the file. On 
input, FileInfoBuf is an BAOP structure above. fpGEAList contents 
are ignored. fpFEAList points to a data area where the relevant 
FEA list will be returned. The length field of chis FEA list is 
valid, giving the size of the FEA list buffer. offfrror is 
ignored. 


On output, FileInfoBuf is unchanged. The buffer pointed to by 
fpFEAList is filled with the returned information. 


It is important that applications expecting to be compatible with 
future versions of OS/2 not use this infolevel, since the limit on 
the size of the full EA List will be raised. Thus, this level is 
documented for utility and system use only. 
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It the buffer fpFEAList points to isn't large enough to hold the 


retucned information (ie ERROR_BUFFER OVERFLOW) cbList will stil) 
be valid. 
RARARARRAARRKRAL yeh of the UNPUBLISHED FUNCTION* @2 eee ante rrankan 
FileInfoBuf is the storage area where the system returns the 
requested level] of file information. 
FileinfoBufSize is the length of FilelnfoBuf. 
Returns: If ERROR {AX not = QO) 
AX = Error Code: 
*  ERROR_INVALID LEVEL ~ the specified FileInfoLevel is not 
valid. 
*  ERROR_INVALID HANDLE ~- the handle is not in use or is 
attached to a physical device. 
* ERROR_DIRECT_ACCESS HANDLE - the specified handle is 
opened with the direct open bit set. 
* ERROR BUFFER OVERFLOW - Lhe specified buffer is not long 
enough to return the desired information. 
* Device-driver/device-manager errors listed %------ ----- 
sates She eS me "= on page ---. 
* ERROR_INVALID EA NAME - there jis an illegal character’ in 
an EA name. The offEcror field points to the of fending 
GEA. 
" _ ERROR EA_LIST_INCONSISTENT - the cbList does not match the 
sum of the lengths of the GEA structures. 
* ERROR_ACCESS DENIED - the specified file 1s not open for 
read access. 

Remarks The FAT file system supports only the modification date and time. 
Zero will be returned fur the creation and access dales and times. 
DosQFileiInto for all infolevels wil) work only for files opened in 
open-for-read of open-for-both/deny-write mode. 
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2.1.8.6.31 DosQFileMode ~- Query File Mode: 


Purpose 


Format 


Where 


Returns: 


Remarks 


2.0 Functional Characteristics 


Query the mode (attribure) of the specified File. 


Calling Sequence: 


EXTRN DosQFileMode:FAR 


PUSH® ASCIIZ FilePathName ; File path name 

PUSH@ WORD CurrentAttribute ; Data area 

PUSH DWORD 0 ¢ Reserved (must be zero) 
CALL DosQFileMode 


FilePathName is the ASCI1I2 file path name. 


CurrentAttribute is where the system returns the file’s current 
attribute. 


IF ERROR {AX not = 0) 
AX = Error Code: 


* ERROR_PATH_NOT_FOUND —- a component of the directory path 
is not present. 


* ERROR FILE NOT FOUND - the last component of the file name 
is not present on the media. 


* ERROR_FILENAME EXCED RANGE - the path 


apecified is 
Unacceptable to the FSD managing the volume. . 


® Device-driver/device-manager errors listed "------ ----- 


SSKne. Sane See “ on page ---. 


The ‘Volume Label’ type attribute is not returned by DosQFileMode, 
DosQFsInfo may be used for this purpose. 


File attributes are defined as follows. 


00001 read only file. 
0x0002 hidden file. 
0x0004 system file. 
0x0010 subdirectory. 
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0x0020 file archive. 
All other attributes are reserved. 


DosQSysinfo must be used by an application to detemine the 
Maximum path length supported by 05/2. The returned value should 
be used Co dynamically allocate buffers that are to be used to 
store paths. This will ensure that applications function 
correctly (wrt path lengths) for future versions of OS/2. The 
path length includes the drive specifier (i.e. d:)}, the leading 
*“\' and the trailing NUL. 
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2.1.8.6.32 DosQFsAttach - Query attached FSD information: 


Purpose 


Format 


Where 


Query information about an attached remote file system or a local 
file system or about a character device or about pseudo-character 
device name attached to a local or remote FSD. 


Calling Sequence: 


EXTRN DosQFsAttach:FAR 


PUSH@ ASCIIZ DeviceName 
PUSH WORD Ordinal 

PUSH WORD FSAInfoLevel 
PUSH@ OTHER DataBuf fer 
PUSH@ WORD Dat abuf ferLen 
PUSH DWORD 0 

CALL DosQFsAttach 


Device name or ‘d:° 

Ordinal of entry in name list 

Type of attached FSD data required 
Returned data buffer 

Buffer length 

Reserved (must be zero) 


Se Gr Be F, Ge M8 


DeviceName points to the drive letter followed by a colon, or 
Points to a character or pseudo-character device name, or is 
ignored for some values of FSAInfoLevel. If DeviceName is a 
drive, it is an ASCIIZ string having the form of drive letter 
followed by a _ colon. If DeviceName is a character or 
pseudo-character device name its format is that of an ASCIIZ 
string in the format of a OS/2 filename in a subdirectory called 
\DEV\. 


Ordinal is an index into the list of character or pseudo-character 
devices, or the set of drives. Ordinal always starts at 1. The 
Ordinal position of an item in a list has no significance at all, 
Ordinal is used strictly to step through the list. The mapping 
from Ordinal to item is volatile, and may change from one call to 
DosQFsAttach to the next. 


FSAInfoLevel is the level of information required, and determines 
which item the data in DataBuffer refers to. 


Level 0x0001 returns data for the specific drive or device name 
refered to by DeviceName. The Ordinal] field is ignored. 


Level 0x0002 returns data for the entry in the list of character 
or pseudo-character devices selected by Ordinal. The DeviceName 
field is ignored. 


Leve] 0©x0003 returns data for the entry in the list of drives 
selected by Ordinal. The DeviceName field is ignored. 


DataBuffer is the return information buffer, it is in the 
following format: 
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Struct | 
unsigned short iType; 
unsigned short cbName; 
unsigned char szName[]; 
unsigned short cbFSDName; 
unsigned char szFSDNamej{); 
unsigned short cbFSAData; 
unsigned char rqgFSAData{]; 

I; 


iType type of item 
* 1 = Resident character device 


e 2 Pseudo-character device 


# 


ad 3 Local drive 


tt 


. 4 + Remote drive attached to FSD 
cbName Length of item name, not counting null. 
SzName Item name, ASCIIZ string. 
cbFSDName Length of FSD name, not counting null. 
SZESDName Name of FSD item is attached to, ASCIIZ string. 
cbFSAData Length of FSD Attach data returned by FSD. 


rgFSAData FSD Attach data returned by FSD. 


szFSDName is the FSD name exported by the FSD, which 1s not 
necessarily the same as the FSD name in the boot sector. 


For jocal character devices {iType = 1), cbhFSDName = 0 and 
SszFSONamée will contain only a terminating NULL byte, and cbFSAData 
= 0. 


For locas drives (iType = 3), szFSOName will contain the name of 
the FSU attached to the drive at the time of the call. This 
information changes dynamically. If the drive is attached to the 
kernel’s resident file system, szFSDName will contain “FAT" or 
“UNKNOWN". Since the resident file system gets attached to any 
disk that other FSUs refuse to MOUNT, it is possible to have a 
disk that does not contain a recognizable file system, but yet 
gets attached to the resident file system. In this case, it is 
possible to detect the difference, and this information would help 
Programs in not destroying data on a disk that was not properly 
recognized. 
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DataHufferLen is the byte tength of the return bufter. Upon 
return, it is the length of the data returned in DataBuffer by the 
FSO. 


IF BRROR (AX not « 0) 
AX = Error Code: 
*  ERROR_INVALID_DRIVE - the drive specified is invalid 


* ERROR _BUFFER_OVERFLOW ~- the specified buffer is too short 
for the returned data. 


* ERROR_NO MORE _ ITEMS - the Ordinal specified refers to an 
item not in the list. ' 


® ERROR_INVALID LEVEL - invalid info level 


Information about all block devices and all character = and 
pseudo-character devices is returned by this call. 


The information returned by this call is highly volatile. Calling 
programs should be aware the the returned information § may have 
already changed by the time it’s returned to them. 


The information returned for disks that are attached to the 
kernel’‘s resident file system can be used to determine if the 
kernel definitely recognized the disk as one with its file system 
on it, or if the kernel just attached its file systemto it 
because no other FSDs MOUNTed the disk. This can be important 
information for a program that needs to know what file system is 
attached to the drive. It is quite easy to gat into a situation 
where the FSD that recognizes a certain disk has not been 
installed into the system. In such a case, there 13 a potentia! 
for the data on the disk to be destroyed since the wrong file 
system will be attached to the disk by default. 
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2-1.8.6.33 DosQFsInfo - Query File System Information: 


Purpose Query information from a file system. 
Format Calling Sequence: 
EXTRN DosQFsInfo:FAR 
PUSH WORD ODOriveNumber ; Drive number 
PUSH WORD FSIinfoLlevel 3 File system data level required 
PUSH@ OTHER FSinftuBuf i File system info buffer 
PUSH WORD FSInfoBbufSize ; File system info buffer size 
CALL DosQFsIntu 
Where DriveNumber 1s the logical drive number {Ocdefault, 1A, 2=B, 3<C, 
~+. ) and represents the FSD for the media currently in that drive 
or the FSD that is currently attached with that drive. 
When a logical drive is specified, the media in the drive is 
examined (local drive only) and the request is passed to the FSD 
responsible for managing that media or to the FSD that is attached 
to the drive (remote case}. 
FSInfoLevel is the level of tile intormation required. 
Level 0x0001 information is returned itn the following format: 
Struct { 
unsigned long reserved; 
unsigned long csecPecAl loc; 
unsigned long callocTotal; 
unsigned long cal locFree; 
unsigned short cbPercSec; 
he 
Leve} 0x0002 information is returned in the following format: 
struct { 
unsigned long ul VSN; 
unsigned chart cbVeol Label; 
unsigned char seVolLabel{|; 
be 
ulVSN volume serial number 
cbVolLabel length of volume label 
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szVolLabel asciiz volume label 


FSInfoBuf is the storage area where the system returns the 
requested level of flle system information. 
FSInfoBufSize is the length of FSInfoBuf. 
IF ERROR (AX not = 0) 
AX = Error Code: 


*  ERROR_INVALID DRIVE - the drive specified is invalid 


* ERROR_BUFFER_OVERFLOW - the specified buffer is too short 


for the returned data. 


* ERROR_INVAL1D LEVEL - the specified FSInfoLevel is not 
supported. 

* Device-driver/device-manager errors listed “-~---~ ----- 

Teme seen enone " on page ---. 


Trailing blanks supplied at volume label definition time are not 
considered to be part of the label and are therefore not returned 
as valid label data. Volume label is limited to a length of 11 
bytes. 


Volume Serial Number is a unique 32-bit number used by 05/2 to 
positively identify its disk/diskette volumes. The hard error 
daemon will prompt the user for an unmounted removable volume. by 
displaying both the Volume Serial Number (as an 8&8 digit 
hexadecimal number) and the Volume Label. 


If there is no volume serial number on the disk/diskette, the 
volume serial number information will be returned as binary zeros. 


If there is no volume label on the disk/diskette, the volume labe} 
information will be returned as blank spaces. 


If there is no volume serial number and/or volume label tor 


disk/diskette volumes formatted by DOS 3.X, this information is 
not displayed by the Hard Error Handler. 
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2.1.8.6.34 DosQHandType - Query a Handle Type: 
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FlagWord is where the system returns the device's driver 
attribute word if HandType tndicates a local character device. 


Purpose Determines whether a handie references a file or a device. 
Returns: IF ERROR (AX not = 0) 
Format Calling Sequence: 
AX = Error Code: 
EXTRN DosQHandType :FAR * ERROR INVALID_HANDLE - the handle is not in use or is 
attached to a physical device. 
PUSH WORD FtleHandle :; Flle handle 
PUSH® WORD HandType ; Handle type response 
PUSH@ WORD FlagWord : Device descriptor word Remarks This function allows some programs which may be interactive ox 
CALL DosQHandType file-oriented to determine the source of their input. For example, 
CMD.EXE supresses writing prompts if the input is from ai disk 
file. 
Where ’ 
FileHandle is the tile handle. 
HWandType is where the system returns the value indicating the 
handle type. HandType is composed of two bytes: 
HandileClass Describes the handle class. It may take on the 
following values in the low byte of HandleType: 
" 0, handie ia for a disk file. 
* 1, handle is for a character device. 
a 2, handle is tor a pipe. 
Values greater than 2 are reserved. 
HandleBits Provides further information about the handle in the 
high byte of HandleType. This byte is broken into eight 
bits, whose meaning depends upon the value af 
HandleClass: 
HandleBlts HandieClass 
§$43210948 7 ----- 6 
Disk file NuuvuuUu UU 0 
Char device Nuuuuuuy iu l 
Pipe Nuuugaowvuudo 2 
N is the NETWORK bic. If set, it meana that the handle 
refers to a remote file, device, or pipe. Otherwise, 
the handle refers to a local file, device, or pipe. 
u means that the bit is undefined and reserved. A 
program may not depend upon the values of these bits, as 
they may change in future versions of OS/2. 
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2.1.8.6.35 DosQPathInfo - Query a file or a subdirectory for information: 
Purpose Returns information for a specific file or subdirectory. 


Format Calling Sequence: 


EXTRN DosQPathIinfo:FAR 


PUSH®@ ASCI1Z PathName 

PUSH WORD PathinfoLevel 
PUSH@ OTHER PathInfoBuf 
PUSH WORD PathInfoBufSize 
PUSH DWORD 0 

CALL DosQPathInfo 


File/directory name 
Data required 

Data buffer 

Data buffer size 
Reserved {must be zero} 


ee te Be Ye fe 


Where PathName is the ASC1IZ full path name of the file-or subdirectory. 
Meta characters are legal in the name only for PathInfoLevels five 


and six. 


PathInfoLevel is the level of path information required. 


Path information, where applicable, is based on the most recent 


DosClose, DosSetFileiInfo, or DosSetPathInfo. 


Level 0x0001 information is returned in the following format: 


struct { 
unsigned short dateCreate; 
unsigned short timeCreate; 
unsigned short dateAccess; 
unsigned short timeAccess; 
unsigned short dateWrite; 
unsigned short timeWrite; 
long cbEOF; 
long cbAlloc; 
unsigned short attr; 


}s 


Level 0x0002 simply adds cbList to level 0x0001, and uses 
following format: 
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struct { 
unsigned short dateCreate; 
unsigned short timeCreate; 
unsigned short dateAccess; 
unsigned short timeAccess; 
unsigned short dateWrite; 
unsigned short timeWrite; 
long cbEOF; 
long cbAlloc; 
unsigned short attr; 
unsigned long’ cbList; 


Level 0x0003 path information, returns a subset of the EA 
information for the file. On input, PathInfoBuf is an EAOP 
Structure above. fpGEAList points to a GEA list defining the 
attribute names whose values will be returned. fpFEAList points 
to a data area where the relevant FEA list will be returned. The 
length field of this FEA list is valid, giving the size of the FEA 
list buffer. offError points to the offending GEA entry in case 
of error. 


On output, PathInfoBuf is unchanged. The buffer pointed to by 
fpFEAList is filled in with the returned information. 


If the buffer fpFEAList points to isn’t large enough to hold the 
returned information (ie ERROR_BUFFER_OVERFLOW) cbList will still 
be valid, assuming there's at least enough space for it. Its 
value will be the size of the entire EA set for the file, even 
though only a subset of attributes was requested. 


***THE FOLLOWING UNPUBLISHED FUNCTION WILL GO AWAY IN FUTURE ***** 
***RELEASES AND SHOULD BE UNPUBLISHED*** 


Level 0x0004 path information returns al] BA info for the file. On 
input, PathInfoBuf is an EAOP structure above. fpGEAList contents 
are ignored. fpFEAList points to a data area where the relevant 
FEA list will be returned. The length field of this FEA list is 
valid, giving the size of the FEA list buffer. offError is 
ignored. 


On output, PathInfoBuf is unchanged. The buffer pointed to by 
fpFEAList is filled in with the returned information. 


It is important that applications expecting to be compatible with 
future versions of OS/2 not use this infolevel, since the limit on 
the size of the full EA list will be raised. ‘Thus, this level is 
documented for utility and system use only. 
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+ If the buffer fpFEAList points to isn’t large enough to hold thel+ 
+ returned information (ie ERROR_BUFFER_ OVERFLOW) cbList will still 
+ be valid. 
+ suakektekeeeeEnd of the UNPUBLISHED FUNCTION*## Ra kkttatenwans 
Level 0x0005 path information returns the fully qualified (true) 


( ASCIIZ name of PathName in PathInfoBuf. 
| meta characters. 


The pathname may contain 


Level 0x0006 requests a file 
| PathName per its rules 
| by an error 
! characters. 


system to verify the correctness of 
of syntax. An erroneous name is indicated 
return-code. The pathname may contain meta 


PathinfoBuf is the storage area where the system returns the 
8 requested level of path information. 
* PathInfoBufSize is the length of PathInfoBuf. 
Returns: IF ERROR (AX not = 0) 
AX = Error Code: 
* ERROR_FILENAME EXCED RANGE - the path specified is 
unacceptable to the FSD managing the volume. 
* ERROR _PATH_NOT_ FOUND - a component of PathName is not 
found. 
* ERROR BUFFER_OVERFLOW - the specified buffer is too short 
| for the returned data. 
| * ERROR_INVALID_LEVEL - the specified PathInfoLevel is not 
| supported. 
* Device-driver/device-manager errors listed “------ -<---- 
See Soe Pa "on page ---. 
* ERROR _INVALID_EA_NAME - there is an fllegal character in 
an EA name. The offError field points to the offending 
GEA. 
* £RROR EA LIST_INCONSISTENT ~- the cbList does not match the 
+ sum of the lengths of the GEA structures. 
+ * ERROR SHARING VIOLATION - the associated file or directory 
+ is being accessed. 


+ Remarks: DosQPathInfo requires read/deny write sharing access for all 
+ infolevels, and will fail if some process holds conflicting 
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sharing rights to the file or directory. 
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* 2.1.8.6.36 DosQSysInfo - Query System Information: 


* Purpose Query static system variables 


Format Calling Sequence: 

i EXTRN DosQSysInfo:FAR 

* PUSH WORD Index ; Which variable 

- PUSH@ OTHER DataBuf : System info buffer 
* PUSH WORD DataBufLen ; Data buffer size 

s CALL DosQSysInfo 


* Where 

* Index is the ordinal of the system variable to return. 

j * Index == 0 indicates maximum path length. The maximum path 
i length will be returned in the first word of the DataBuf. 

" DataBuf is where the system returns the variable value. 

. DataBufLen is the length of the data buffer. 


* Returns: IF ERROR {AX not = 0) 


sd AX = Error Code: 
* * ERROR_INVALID PARAMETER - the index is invalid. 
* * ERROR_BUFFER_OVERFLOW - the specified buffer is too short 
n for the returned data. 
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2.1.8.6.37 DosQVerify - Query Verify Setting: 
Purpose Returns the value of the Verify flag. 
Format Calling Sequence: 

EXTRN DosQVerify:FAR 


PUSH@ WORD VerifySetting ; Verify setting 
CALL DosQVerify 


Where VerifySetting is the current Verify mode for the requesting 


process 


* If value = 0x00 is returned, verify mode is not active 


* If value = 0x01 is returned, verify mode is active 


Returns: IF ERROR {AX not = QO) 
AX = Error Code: 


* none 


Remarks 
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2.1.8.6.3B8 DosRead - Read from a File: 


Purpose 


Format 


Where 


Returns: 


Remarks 


Reads the specified number of bytes froma file toa buffer 
location. 


Calling Sequence: 


EXTRN DosRead:FAR 


PUSH WORD FileHandle 
PUSH@ OTHER BufferArea 
PUSH WORD Buf ferLength 
PUSH@ WORD BytesKead 
CALL DosRead 


File Handle 

Address of user buffer 
Buffer length 

Bytes read 


Sa, Be Bs te 


FileHandie ts the 2-byte {lle handle obtained from DosOpen. 
BufferArea is address of the input buffer. 
HufferLength is the number of bytes to be read. 
HytesRead is where the system ceturns the number of bytes read. 
IF ERROR (AX not = 0) 
AX - Error Cade: 


» ERROH_INVALID_HANDLE - the handte is not in use or is 
attached to a physical device. 


a ERROR_ACCESS DENIED - the handle is opened as write-only. 


‘ ERROR LOCK VIOLATION ~- the region of the file is partially 
or completely locked by another process. 


e Device-driver/device-manager errors \jisted S------ -=<--- 
She. ae See ee “on page ---. 


It 4s not guaranteed that the requested number of bytes will be 
read. 


A BufferLength value of zero is not considered an error. In the 
case when the value of BulferLength is zero, the system treats 
the request as a null operation. 


Named Pipe Considerations Reads bytes or messages from a pipe. There are 


three cases: 


1. Byte ptpe. The plpe must be in byte read mode {an error is 
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returned if in message read mode). All currently available 
data, up to the size requested, is returned. 


2. Message pipe, message read mode. A cead that is larger chan 
the next available message returns only that message and 
BytesRead is set to indicate the size of the message 
returned. A read that is smaller than the next available 
message returns with the number of bytes cequested and a MOHE. 
DATA error code. Subsequent DosReads will continue reading 
the message. DosPeekNwPipe may be used to determine how many 
bytes are left in the message. 


3. Message pipe, byte read mode. Reads the pipe as if it were a 
byte stream, skipping over message headers. This is like 
reading a byte pipe in byte mode. 


When blocking mode is set, a read blocks until data is available. 
In this case, the read will never return with BytesRead=0 except 
at EOF. Note that in message read mode, messages are always read 
in their ENTIRETY, except in the case where the message is bigger 
than the size of the cead. 


When nonblocking mode is set, a read will return with BytesRead-0 
at EOF. An error will be returned if there is no data available. 


Note: when resuming the reading of a message after a MORE DATA 
indication, the reads will always block until the next piece (or 
rest) of the message can be transferred. Non-blocking mode only 
allows a return with BytesRead=0 when trying to read at the start 
of a message and no message is available. 


2.0 Functional Characteristics 196 


00103 


cv SPE SIV 0 d3 


Microsoft Confidential 
OS/2 1.2 IFS Patent Documentation 


2.1.8.6.38 DosRead - Read froma File: 


Purpose 


Format 


Where 


Returns: 


Remarks 


Reads the specified number of bytes froma file toa 
location. 


Calling Sequence: 


EXTRN DosRead:FAR 

PUSH WORD FileHandle File Handle 

PUSH@ OTHER BufferArea Address of user buffer 
PUSH WORD BufferLength ; Buffer length 

PUSH@ WORD BytesRead 3; Bytes read 

CALL DosRead 


FiieHandle is the 2-byte file handle obtained from DosOpen. 


BufferArea 1s address of the input buffer. 


BufferLength is the number of bytes to be read. 


buffer 


BytesRead is where the system returns the number of bytes read. 


IF ERROR (AX not = Q) 


AX = Error Code: 


* ERROR_INVALID_ HANDLE - the handle is not in use or is 


attached to a physical device. 


® ERROR_ACCESS DENIED - the handle is opened as write-only. 


* ERROR_LOCK VIOLATION - the region of the file is partially 
or completely locked by another process. 


7 Device-driver/device-manager errors listed “---<-- <----- 


Saeae Sere asee< *" on page ---. 


It is not quaranteed that the requested number of bytes will be 
read. 


A BufferLength value of zero is not considered an error. In the 


case when the value of BufferLength is zero, the system treats 
the request as a null operation. 


Named Pipe Considerations Reads bytes or messages from a pipe. There are 


three cases: 


1. Byte pipe. The pipe must be in byte read mode (an error is 
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returned if in message read mode). All currently available 
data, up to the size requested, is returned. 


2. Message pipe, message read mode. A read that is larger than 
the next available message returns only that message and 
BytesRead is set to indicate the size of the message 
returned. A read that is smaller than the next available 
message returns with the number of bytes requested and a MORE 
DATA error code. Subsequent DosReads will continue reading 
the message. DosPeekNmPipe may be used to determine how many 
bytes are left in the message. 


3. Message pipe, byte read mode. Reads the Pipe as if it were a 
byte stream, skipping over message headers. This is like 
reading a byte pipe in byte mode. 


‘ 


When blocking mode is set, a read blocks until data is available. 
In this case, the read will never return with BytesRead=0 except 
at EOF. Note that in message read mode, messages are always read 
in their ENTIRETY, except in the case where the message is bigger 
than the size of the read. 


When nonblocking mode is set, a read will return with BytesRead=0 
at EOF. An error will be returned if there is no data available. 


Note: when resuming the reading of a message after a MORE DATA 
indication, the reads will always block until the next piece (or 
rest) of the message can be transferred. Non-blocking mode only 
allows a return with BytesRead=0 when trying to read at the start 
of a message and no message is available. 
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2.1.8.6.39 DosReadAsync - Async Read from a Fille: 


Purpose 


Format 


Where 


Returns: 


Remarks 


fransfers the specified number of bytes from a handle to a buffer 
location, asynchronously with respect to the requesting process's 
execution. 


Calling Sequence: 


EXTRN DosReadAsync :FAR 


PUSH WORD FileHandle File handle 


PUSH@ DWORD RamSemaphore ; Address of Ram semaphore 
PUSH@ WORD ReturnCode 3; Address of I/O error RC 
PUSH@ OTHER BufferArea : Address of user buffer 
PUSH WORD BufferLength ; Buffer length 

PUSH@ WORD BytesRead ; Bytes read 

CALL DosReadAsync 


FileHandle is the 2-byte file handle obtained from DosOpen. 


RamSemaphore is used by the system to post operation complete to 
the caller. 


ReturnCode is where the system returns the I/O operation return 
code. 


BufferArea is address of the input buffer. 
BufferLength is the number of bytes to be read. 
BytesRead is where the system returns the number of bytes read. 
AX = 0 ReturnCode = Error code if error 
AX = Error Code: 


* ERROR_INVALID_HANDLE - the handle is not in use or is 
attached to a physical device. 


* BRROR ACCESS DENIED - the handle is opened as write-only. 


* ERROR_LOCK_ VIOLATION - the region of the file is partially 
or completely locked by another process. 


*  Device-driver/device-manager errors listed "------ ----- 
ssa Sees Se " on page --~. 


It is not guaranteed that the requested number of bytes will be 


read. 


2.0 Functional Characteristics 197 


Microsoft Confidential 
OS/2 1.2 IFS Patent Documentation 


A BufferLength value of zero is not considered an error. In the 
case when the value of BufferLength is zero, the system treats 
the request as a null operation. 


RamSemaphore must be set by the application before’ the 
DosReadAsynec call is made. The application issues the following 
sequence: 

* DosSemSet eee 


* DosReadAsync re 


* DosSemWait ae 


Named Pipe Considerations Reads bytes or messages from a pipe. There are 


three cases: 


1. Byte pipe. The pipe must be in byte read mode (an error is 
returned if in message read mode). Al! currently available 
data, up to the size requested, is returned. 


2. Message pipe, message read mode. A read that is larger than 
the next available message returns only that message and 
BytesRead is set to indicate the size of the message 
returned. A read that is smaller than the next available 
message returns with the number of bytes requested and a MORE 
DATA error code. Subsequent DosReads will continue reading 
the message. DosPeekNmPipe may be used to determine how many 
bytes are left in the message. 


3. Message pipe, byte read mode. Reads the pipe as if it were a 
byte stream, skipping over message headers. This is like 
reading a byte pipe in byte mode. 


When blocking mode is set, a read blocks until data is available. 
In this case, the read will never return with BytesRead=0 except 
at EOF. Note that in message read mode, messages are always read 
in their ENTIRETY, except in the case where the message is bigger 
than the size of the read. 


When nonblocking mode is set, a read will return with BytesRead=0 
if no data is available at the time of the read. 


Note: when resuming the reading of a message after a MORE DATA 
indication, the reads will always block until the next piece (or 
rest) of the message can be transferred. Non-blocking mode only 
allows a return with BytesRead=0 when trying to read at the start 
of a message and no message is available. 
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2.1.8.6.40 DosRmDir - Remove Subdirectory: 
Purpose Removes a subdirectory from the specified disk. 


Format Calling Sequence: 


EXTRN DosRmDir :FAR 


PUSH@ ASCIIZ DirName ; Directory name 
PUSH DWORD QO 3; Reserved (must be zero) 
CALL DosRmDir 


Where DirName is the ASCIIZ directory path name. 


Returns: IF ERROR (AX not = 0) 


AX = Error Code: 





* ERROR_FILENAME EXCED_RANGE = the path specified is 


unacceptable to the FSD managing the volume. 


* ERROR_PATH_NOT_FOUND - the drive is invalid or a directory 
in the path is not found. 


* ERROR_CURRENT DIRECTORY -~ the specified path is _ the 
current directory of a process. 


* ERROR_ACCESS DENIED - the root directory is specified, or 
the directory is not empty. 


* Device-driver/device-manager errors listed ieioote uesas 
Sasa ee. ae “ on page ---. 


Remarks The directory must be empty before it can be removed with the 
exception of the ".% and *..". You cannot remove subdirectories 
that contain hidden files. The last directory name in the path is 
the directory to be removed. The root directory and the current 
directory cannot be removed. 


DosQSysInfo must be used by an application to detemine the 
maximum path length supported by OS/2. The returned value should 
be used to dynamically allocate buffers that are to be used to 
store paths. This will ensure that applications function 
correctly (wrt path lengths) for future versions of 05/2. The 
path length includes the drive specifier (i.e. d:), the leading 
*\' and the trailing NUL. 


Geme® Spe fee? feed teed Ged bee 
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2.1.8.6.41 DosScanEnv - Scan Environment Segment: 2.1.8.6.42 DosSearchPath - Search a path for a file name: 
Purpose Scans an environment segment for an environment variable. Purpose Provides a general path search mechanism which allows applications 
to find files residing along paths. The path string may come from 
Format Calling Sequence: the process's Environment, or be supplied directly by the caller. 


Format Calling Sequence: 
EXTRN DosScanEnv: FAR 


PUSH@ ASCIIZ EnvVarName : Environment varitable name EXTRN DosSearchPath:FAR 
PUSH@ DWORD ResultPointer ; Search result pointer 


CALL DosScanEnv PUSH WORD Control : Function control vector 
PUSH@ ASCII2Z PathRef 3; Search path reference 
PUSH@ ASCIIZ FileName ; File name 
Where EnvVarName points to the ASCIIZ name of the environment variable PUSH® OTHER ResultBuffer : Search result buffer 
of interest. Do not include atralling “°=", since this is not PUSH WORD ResultBufferLen ; Search result buffer length 
part of the name. ; CALL DosSearchPath 


ResultPointer is where the system returns the pointer to the 

environment string. ResultPointer points to the first character Where 

of the string which is the value of the environment variable and 

can be passed directly into DosSearchPath. Control is a word bit vector which controls the behaviour of 

DosSearchPath 
Returns: IF ERROR (AX not = 0) 
* Bit 0 = Implied Current Bit 
AX = Error Code: 


+ * Bit 1 = Path Source Bit 
* ERROR_ENVVAR_NOT_FOUND - the specified environment 
variable is not found in the environment segment. + * Bit 2 = Ignore Network Errors Bit 
+ * Bits 3-15 = Reserved bits, must be 0. 
Remarks Assume that the process’s environment contains: 
"DPATH=c: \sysdir;c:\libdir"™ The Implied Current Bit controls whether the current directory is 
A implicitly on the front of the search path. If the Implied 


Current Bit = 0, DosSearchPath will only search the current 
i directory if it appears in the search path. If the Implied 

Current Bit = i, DosSearchPath will search the current'§ working 
+---- ResultPointer points here after call . directory before it searches the directories in the search path. 


to DosScanEnv below. | 
Implied Current Bit = 0 and Path = ".:a;b" 


DosScanEnv("DPATH", é&ResultPointer); 
is equivalent to 


As noted above, ResultPointer will point to the first 
character of the value of the environment variable. Implied Current Bit = 1 and Path = “asb" 


The Path Source Bit determines how DosSearchPath interprets the 
PathRef argument. If the Path Source Bit = 0, then PathRef points 
to the actual search path. The search path string may be anywhere 
in the calling process’s address space, hence it may be in the 
environment, but does not have to be. 
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If the Path Source Bit = 1, then PathRef points to the name of an 
environment variable in the process’s environment, and that 
environment variable contains the search path. 


PathRef points to an ASCIIZ string. 


If the Path Source Bit of Control = O, then PathRef points 
directly to the search path, which may be anywhere in the caller's 
address space. 


If the Path Source Bit of Control = 1, then PathRef points to a 
string which is the name of an environment variable which contains 
the search path. 


A search path consists of a sequence of paths separated by “;". 
It is a single ASCIIZ string. The directories will be searched in 
the order they appear in the path. 


variable names are simply strings which match name 
The "=" sign is not part of the name. 


Environment 
strings in the environment. 


The Ignore Network Errors Bit controls whether the search will 
abort if it encounters a network error or will continue the search 
with the next element. This allows one to place network paths in 
the PATH variable and be able to find executables in components of 
the PATH variable even if the network returns an error, e.g. if a 
server is down. If the Ignore Network Errors Bit «= 0, 
DosSearchPath will abort the search if it encounters an error from 
the network. If the Ignore Network Errors Bit = 1, DosSearchPath 
will continue on the search if it encounters network errors. 


FileName points to the ASCIIZ file name to search for. It may 
contain wild cards. If FileName does contain wild cards, they 
will remain in the result path returned in 


ResultBuffer. This allows applications like cmd.exe to feed the 
output directly to DosFindFirst. If there are no wildcards in 
FileName, the result path returned in ResultBuffer will be a full 
qualified name, and may be passed directly to DosOpen, or any 
other system call. 


ResultBuffer holds the result pathname of the file, if found. If 
FileName is found in one of the directories along the path, its 
full pathname will be returned in ResultBuffer. (With wildcards 
from FileName left in place.) Do not depend on the contents of 
ResultBuffer being meaningful if DosSearchPath doesn’t return 
with AX=0. 


ResultBufLen is the length of ResultBuffer, in bytes. 


IF ERROR (AX not = 0) 
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AX = Error Code: 


* ERROR_BUFFER_OVERFLOW - 
for the returned data. 


the specified buffer is too short 


* ERROR_FILE NOT FOUND - no matching file is found. 
* DPDevice-driver/device-manager errors listed "------ --~~-- 
See Soe meee ”" on page ---. 


PathRef always points to an ASCIIZ string. 
example: 


Let DPATH be an environment variable in the environment segment of 
the process. 


“DPATH=c:\sysdir;sc:\init® /* in the environment */ 


The following two code fragments are equivalent: 


DosScanEnv ("DPATH", ¢PathRef) ; 
DosSearchPath(0, /* Path Source Bit = 0 */ 
PathRef, “myprog.ini", sResultBuffer, ResultBufLen) ; 


DosSearchPath(2, /* Path Source Bit = 1 */ 
"DPATH", "myprog.ini", éResultBuffer, ResultBufLen); 


Both of them use the search path stored as DPATH in the 
environment segment. In the first case, the application uses 
DosScanEnv to find the variable, in the second case DosSearchPath 
calls DosScanEnv for the application. 


DosSearchPath does no consistency checking or formating on the 
names, it simply does a DosFindFirst on a series of names it 
constructs from PathRef and FileName. This means that the 
underlying file system does the name formatting. 


DosQSysinfo must be used by an application to detemine the 
maximum path length supported by 0OS/2. The returned value should 
be used to dynamically allocate buffers that are to be used to 
store paths. This will ensure’ that applications function 
correctly (wrt path lengths) for future versions of 0S/2. The 
path length includes the drive specifier (i.e. d:), the leading 
‘\’ and the trailing NUL. 
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2.1.8.6.43 DosSelectDisk - Select Default Drive: 


Purpose Selects the drive specified as the default drive for the calling 
process. 


Format Calling Sequence: 
EXTRN DosSelectDisk:FAR 


PUSH WORD DriveNumber ¢ Default drive number 
CALL DosSelectDisk 


Where 
DriveNumber contains the default drive number (1#A, 2=B, ... ). 
Returns: IF ERROR (AX not = 0) 
AX = Error Code: 


* ERROR_INVALID_ DRIVE - the specified drive in invalid. 
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2.1.8.6.44 DosSetFHandState - Set File Handle State: 
Purpose Set the state of the specified file. 


Format Calling Sequence: 


EXTRN DosSetFHandState:FAR 
PUSH WORD FileHandle ; File handle 
PUSH WORD FileHandleState ; File handle state 
CALL DosSetFHandState ; 

Where 
FileHandle is the handle of the file to be set. 


FileHandleState is the file handle state and consists of 
following bit fields. They are the: 


* Inheritance flag 
*  Write-through flag 
*  Fail-errors flag 


bd Zero bit field 


File Handle State Bits 


§43210987654321 0 
OWFCRRRRIOOAOOARAOASO 
I Inheritance Flag 


If I = 0; File handle is inherited by a 
spawned process resulting 
from a DosExecPgm call. 

If I = 13; File handle is private to the 
current process. 

This bit is not inherited by child processes. 

Ww File Write-through 
The file is opened as follows: 


If W= 0; Writes to the file may be run 
through the DOS buffer cache. 
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If W=,1; Writes to the file may go 
through the DOS buffer 
cache but, the sectors 
will be written (actual file 
I/O completed) before a 
synchronous write call returns. 
This state of the file defines 
it as a synchronous file. 


NOTE that this is a mandatory bit in that the data MUST be 
written out to the medium for synchronous’ write 
operations. This bit is not inherited by child processes. 


Fail-Errors 
Media 1/0 errors will be handled as follows: 


If F = 0; reported through the system 
critical error handler. 

If F = 1; reported directly to the 
caller via return code. 


This bit is not inherited by child processes. Media 1/0 
errors generated through an IoCtl] Category 8 function, 
always get reported directly to the caller via return 
code. The Fail-Errors§ functionality applies only to 
non-lIoCt] handle-based type file 1/0 calls. 


Cache/No-Cache 


The file is opened as follows: 

If c = 0; I/O to the file need not be done 
through the disk driver cache. 

If C = 1; It is advisable for the disk driver 
to cache the data in I/O operations 
on this file. 


This bit is an ADVISORY bit, and is used to advise FSDs 
and device drivers on whether it is worth caching the data 
or not. This bit, like the write-through bit, is a 
per-handle bit. It is not inherited by child processes. 
zero bits 

These bits must be set to zero. 


Any other values for FileHandleState are invalid. 


Reserved bits 


2.0 Functional Characteristics 207 


Returns: 


Remarks 


Microsoft Confidential 
OS/2 1.2 IFS Patent Documentation 


These bits are reserved and should be set to the values 
returned by DosQFHandState in these positions. 
IF ERROR {AX not = 0) 
AX = Error Code: 


* ERROR_INVALID HANDLE - the handle is not in = use or is 
attached to a physical device. 


* ERROR_INVALID PARAMETER - the specified mode contains 
reserved fields non-zero or contains an invalid value. 


Setting the write-through flag does not affect any previous writes 
which may have been done. That data may remain in the buffers. 


The file handle state bits set by this function can be queried 
with the DosQFHandState function call. 


Named Pipe Considerations Allows setting of the inheritance (I) and 


write-through (W) bits. Note that setting W to 1 prevents 
write-behind operations on remote pipes. 
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2.1.8.6.45 DosSetFileInfo - Set a File’s Information: 
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AX = Error Code: 


ne 
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Purpose Specifies information for a file. * ERROR_INVALID LEVEL - the specified FileInfoLevel is not 
supported. 
Format Calling Sequence: 
* ERROR_INSUFFICIENT BUFFER - the specified buffer is too 
short to contain the stated level of information. 
EXTRN DosSetFileInfo:FAR 
* ERROR_DIRECT ACCESS HANDLE - the handle is opened with the 
PUSH WORD FileHandle : File handle + direct-open bit set. 
PUSH WORD FileInfoLevel ; File info data type 
PUSH@ OTHER FileInfoBuf ; File info buffer ¢ * ERROR_INVALID PARAMETER - invalid times/dates are 
PUSH WORD FileInftoBufSize ; File info buffer size + specified. This may be returned by an FSD if it validates 
CALL DosSetFileiInfo + the date and time. 
* ERROR_INVALID EA NAME - there is an illegal character in 
Where FileHandle is the file handle. an BA name. The offError field points to the offending 
FEA. 
FileInfoLevel is the level of file information being defined. 
j * ERROR_EA_LIST_INCONSISTENT - the cbList does not match the 
Level 0x0001 file information is set from FileInfoBuf in the sum of the lengths of the FEA structures. 
following format: 
* ERROR_EA VALUE_UNSUPPORTABLE - the FSD detects an error in 
the- value portion of an EA. The offError field points to 
struct { + the offending FEA. 
unsigned short dateCreate; 
unsigned short timeCreate; + * ERROR_ACCESS DENIED - the specified file is not open for 
unsigned short dateAccess; + write access. 
unsigned short timeAccess; 
unsigned short dateWrite; * Device-driver/device-manager errors listed "--<---- <----- 
unsigned short timeWrite; 9000000000000 fe remem eemamanan  enanen cn ae * on page ---. 
)e 
* Remarks The DosSetFileInfo level 0x0001 structure is a prefix of the 
Level 0x0002 file information sets a series of EA name/value DosQFileInfo level 0x0001 structure. 
pairs. On input, FileInfoBuf is an EAOP structure above. 
fpGEAList is ignored. fpFEAList points to a data area where the DosSetFileInfo will work only for files opened in a mode that 
relevant FEA list is to be found. offError is ignored. allows write-access. 
On output, fpGEAList is unchanged. fpFEAList is unchanged as is A zero (0) value in both the date and time components of a field 
the area pointed to by fpFEAList. If an error occurred during the will cause that field to be left unchanged. For example, if both | 
set, offError will be the offset of the FEA where the error ‘Last write date’ and ‘Last write time’ are specified as zero in 
occurred. The API return code will be the error code the Level 0x0001 information structure, then both attributes of 
corresponding to the condition generating the error. If no error the file are left unchanged. If either ‘Last write date’ or ‘Last 
occurred, offError is undefined. write time’ are specified as non-zero, then both attributes of the 
file will be set to the new values. 
FileInfoBuf is the storage area where the system gets the file 
information. * The FAT file system supports only the modification date and time. 
* Creation and access dates and times will not be affected. 
FileInfoBufSize is the length of FileInfoBuf. 
Returns: IF ERROR (AX not = 0) 
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2.1.8.6.46 DosSetFileMode - Set File Mode: 


Purpose Change the mode (attribute) of the specified file. 
Format Calling Sequence: 
EXTRN DosSetFileMode:FAR 
PUSH@ ASCIIZ FileName ; File path name 
PUSH WORD NewAttribute ; New attribute of file 
PUSH DWORD 0O ; Reserved (must be zero) 
CALL DosSetFileMode 

Where FileName is the ASCII2 file path name. 
NewAttribute is the file's new attribute. 

Returns: IF ERROR (AX not = 0) 

AX = Error Code: 

* ERROR_PATH_NOT_ FOUND - a component of the directory path 
is not present. 

* ERROR_FILE NOT_FOUND - the last component of the file name 
is not present on the media. 

* ERROR_FILENAME_EXCED RANGE - the path’ specified is 
unacceptable to the FSD managing the volume. 

* ERROR_ACCESS_DENIED - the attributes are invalid or the 
specified file name is a character device or a _ root 
directory was specified. 

" ERROR_SHARING BUFFER_EXCEEDED - there is not enough memory 
to hold sharing information. 

* ERROR SHARING VIOLATION - the file is currently in use by 
another process. 

Device-driver/device-manager errors listed ®%------ <-7%-- --<--- 

Ss SSeS “ on page ---. 

Remarks Attributes for Volume Label (0x0008) or Subdirectory (0x0010) 
Cannot be set using DosSetFileMode. If the above referenced 
attributes are used to change a file’s mode, an error code is 
returned. Attributes of root directories cannot be changed and an 
error will be returned. 
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File attributes are defined as follows. 


0x0001 read only file. 
0x0002 hidden file. 
0x0004 system file. 
0x0008 volume label. 
0x0010 subdirectory. 
0x0020 file archive. 


All other attributes are reserved. 

DosQSysinfo must be used by an application to detemine the 
maximum path length supported by OS/2. The returned value should 
be used to dynamically allocate buffers that are to be used to 
store paths. This will ensure that applications function 
correctly (wrt path lengths) for future versions of OS/2. The 
path length includes the drive specifier (i.e. d:), the leading 
*"\’ and the trailing NUL. 
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2.1.8.6.47 DosSetFsInfo - Set File System Information: 


Purpose 


Format 


Where 


Returns: 


Set 


Call 


EXTR 
PUSH 
PUSH 
PUSH 


PUSH 
CALL 


Driv 


driv 
ASCI 


FSIn 
Leve 
Leve 


stru 


); 

cbVo 
szVo 
FSIn 
info 
FSiIn 


IF 


information for a file system device. 


ing Sequence: 


N DosSetFsiInfo:FAR 


WORD DriveNumber ; Drive number 
WORD FSInfoLevel ; File system data type 
@ OTHER FSInfoBuf ; File system info buffer 
WORD FSInfoBufSize ; Flie system info buffer size 


DosSetFsinfo Remarks 
eNumber is the logical drive number (O=default, 1#A,2=B,3=C, 
) and represents the FSD for the media currently in that 
e. A value of ‘OxFFFF’ notes that FSInfoBuf contains the 
IZ path name of the FSD. 
foLevel is the level of file information to set. 
. 0x0001 is reserved. 
1] 0x0002 information is defined in the following format: 
ct { 
unsigned char cbVolLabel; 
unsigned char szVolLabel|[]; 
lLabel length of volume label 
lLabel asciiz volume label. 
foBuf is where the system gets the new file system 
rmation. 
foBufSize is the length of FSInfoBuf. 
ERROR (AX not = 0) 
AX = Error Code: 
ba ERROR_INVALID_ LEVEL - the specified FSInfoLevel is not 


supported. 
* ERROR INVALID DRIVE - the specified drive is invalid. 


* ERROR_CANNOT_ MAKE ~- cannot create volume fabel 


2.0 Functional Characteristics 


213] 2.0 Functional Characteristics 


Microsoft Confidential 
OS/2 1.2 IFS Patent Documentation 


ERROR INVALID NAME - there are characters in the volume 
label that are illegal. 


ERROR_INSUFFICIENT BUFFER - the specified buffer is too 
short to contain the stated level of information. 


ERROR_LABEL TOO LONG - the volume label exceeded the file 
systems name capacity. 


Device-driver/device-manager errors listed “------ ----- 


SSS SSS 9> SS Sa-= *" on page -~--. 


Trailing blanks supplied at volume label definition time are not 
returned by DosQFsInfo. 
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2.1.8.6.48 DosSetMaxFH - Set Maximum File Handles: 2.1.8.6.49 DosSetPathInfo - Set a File’s or Directory’s Information: 


Purpose This function call defines the maximum number of file handles for Purpose Specifies information for a file or a directory. 
the current process. 


Format Calling Sequence: 
Format Calling Sequence: 
EXTRN DosSetMaxFH:FAR EXTRN DosSetPathInfo:FAR 
PUSH WORD NumberHandles ; Number of file handles PUSH@ ASCTIIZ PathName File/dir full name 


CALL DosSetMaxFH PUSH WORD PathInfoLevel 


PUSH@ OTHER PathiInfoBuf 
PUSH WORD PathInfoBufSize 


PUSH WORD PathInfoFlags 
NumberHandles is the total number of file handles to be provided. PUSH DWORD 0 


Info data type 

Info buffer 

Info buffer size 

Flags 

Reserved (must be zero) 
CALL DosSetPathInfo ' 


Where 


oS oe = 


"ep te te Se Ve Yo 


Returns: IF ERROR (AX not «= 0) 





AX = Error Code: | Where PathName is the ASCIIZ full path name of the file or subdirectory. 
[ This name may not contain meta characters. 
* ERROR_NOT_ ENOUGH MEMORY - unable to allocate storage for 
new file handle table. | PathInfoLevel is the level of file/directory information being 
defined. 
* ERROR_INVALID PARAMETER - the requested number of file 
handles is > 32768 or the requested number is smaller than Level 0x0001 file information is in the following format: 
the currently allocated set. 


struct { 
unsigned short dateCreate; 
Remarks All currently open file handles are preserved. unsigned short timeCreate; 


unsigned short dateAccess; 
unsigned short timeAccess; 
unsigned short dateWrite; 
unsigned short timeWrite; 


Level 0x0002 file information sets a series of EA name/value 
i pairs. On input, PathInfoBuf is an EAOP structure above. 
| fpGEAList is ignored. fpFEZAList points to a data area where the 
relevant FEA list is to be found. offError is ignored. 


* On output, fpGEAList is unchanged. fpFEAList is unchanged as is 

* the area pointed to by fpFEAList. If an error occurred during the 
set, offError will be the offset of the FEA where the error 
occured. The API return code will be the error code corresponding 
to the condition generating the error. If no error occurred, 
offError is undefined. 


| PathInfoBuf is the storage area where the system gets the file 
information. 


| PathInfoBufSize is the length of PathInfoBuf. 
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PathInfoFlags contain information on how the Set operation is to 
be performed. Currently, only one bit is defined. If PathInfoFlags 
== 0x0010, then this indicates that the information being set must 
be written out to disk before returning to the application. This 
guarantees that the EAs have been written to disk. All other bits 
are reserved and must be zero. 


IF ERROR (AX not = QO) 
AX = Ercror Code: 


* BRROR_INVALID_LEVEL - the specified PathInfoLevel is not 
supported. 


* ERROR INVALID PARAMETER - invalid times/dates are 
specified. 
This may be returned by an FSD if it validates 
and time. 
* ERROR FILENAME_EXCED_ RANGE - the path specified is 


unacceptable to the FSD managing the volume. 


* ERROR_INSUFFICIENT_ BUFFER - the specified buffer is too 
short to contain the stated level of information. 


- there is an illegal character in 


. ERROR_INVALID_EA_NAME 
field points to the offending 


an EA name. The offError 
FEA. 


* £RROR EA LIST INCONSISTENT - the cbList does not match the 
sum of the lengths of the FEA structures. 


* BRROR EA_VALUE_UNSUPPORTABLE - the FSD detects an error in 
the value portion of an EA. The offError field points to 


the offending FEA. 


#  £RROR SHARING VIOLATION - the associated file or directory | 


is being accessed. 


Device-driver/device-manager errors listed “---9<- sere- ererm 
weer oo *" on page ---. 
DosSetPathInfo requires read/deny_write sharing access for all} 
infolevels, andwill fail if some process holds conflicting 


sharing rights to the file or directory. 


A zero (0) value in both the date and time components of a field 
will cause that field to be left unchanged. For example, if both 
‘Last write date’ and ’Last write time’ are specified as zero in 
the Level 0x0001 information structure, then both attributes of 
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the file are left unchanged. If either ‘Last write date’ or ‘Last 
write time’ are specified as non-zero, then both attributes of the 
file will be set to the new values. 


The write-through bit in PathInfoFlags should be used only in 
cases where it is necessary, for data integrity purposes, to write 
the EAs out to disk immediately, instead of caching them and 
writing them out later. Setting the write-through bit all the time 
may degrade the performance. 
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2.1.8.6.50 DosSetVerify - Set/Reset Verify Switch: 


Purpose 


Format 


Where 


Returns: 


Remarks 


Sets the verify switch. 
Calling Sequence: 
EXTRN DosSetVerify:FAR 


PUSH WORD VerifySetting ; New value of verify switch 
CALL DosSetVorify 


VerifySetting is the new state of Verify Mode for the requesting 


process 
* lf value + 0 is specified, Verify Mode is deactivated 
* lf value = 1 is specified, Verify Mode is activated 
IF ERROR (AX not = 0) 
AX = Error Code: 


sy ERROR_INVALID_ VERIFY SWITCH 


When verify is on, device drivers are requested to perform a 


verify-after write operation each time they do a file 
assure proper data recording on the disk. 
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4 2.1.8.6.51 DosShutdown - Shutdown File Systems for Power Off: 


+ 
+ 


+ 


+ 


+ Returns: 


+ 


+ 


+ + 


-~+ +44 + + + 


++ 


Purpose 


Format 


Where 


Remarks 


Locks out changes to all file systems. Forces system buffers to 
disk in preparation for system power off. 


Calling Sequence: 


EXTRN DosShutdown:FAR 


PUSH DWORD Reserved : Reserved Zero 
CALL DosShutdown 


Reserved is a dword whose value must be zero. 
IF ERROR (AX not = Q) 
AX = Error Code: 
* ERROR_IN_PROGRESS - a shutdown is already in progress. 


* ERROR_CANNOT SHUTDOWN - the system was unable to shutdown 
one or more file systems. 


* ERROR_INVALID PARMS ~ the reserved word was non-zero. 


This function may take several minutes to complete depending on 
the amount of data buffered. 


APIs that change file system data called while the system is 
shutdown will either return the error ERROR_SYSTEM SHUTDOWN or 
block permanently. 


It should be noted that it will not be possible to increase memory 
overcommit once the DosShutdown has been called. This means that 
in low memory situations some functions may fail due to a lack of 
memory. This is of particular importance to the process calling 
DosShutdown. All memory that the calling process will ever need 
should be allocated before calling DosShutdown. This includes 
implict memory allocation that may be done on behalf of the caller 
by system functions. 


When this api returns successfully, it is safe to power the system 
off or to reboot it. 
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2.1.8.6.52 DosWrite - Synchronous Write to a File: 


Purpose 


Format 


Where 


Returns: 


Remarks 


Transfers the specified number of bytes from a buffer to the 
specified file, synchronously with respect to the requesting 
process's execution. 


Calling Sequence: 


EXTRN DosWrite:FAR 


PUSH WORD FileHandle ; File handle 
PUSH@ OTHER BufferArea : 
PUSH WORD BufferLength ; Buffer length 
PUSH@ WORD BytesWritten ; 

CALL DuosWrite 


Address of user buffer 


Bytes written 


FileHandle is the 2-byte file handle obtained from DosOpen. 
BufferArea is address of the output buffer. 
BufferLength is the number of bytes to be written. 


BytesWritten is where the system returns the number of bytes 
written. 


IF ERROR (AX not = Q) 
AX = Error Code: 


* ERROR INVALID HANDLE - the handle is not in use or is 
attached to a physical device. 


# £RROR LOCK _VIOLATION - the region of the file is partially 
or completely locked by another process. 


* ERROK ACCESS _DENIED - the file is opened as read-only. 


* Device-driver/device-manager errors listed “----<7 <<-=-- 
corner conn * on page ---. 


Upon return from this function, BytesWritten is the number of 
bytes actually written. 


A BufferLength value of zero {is not considered an error. In the 
case when the value of BufferLength is zero, the system treats 


the request as a null operation. 
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Named Pipe Considerations Writes bytes or messages to a pipe. Each write 


to a message pipe writes a message whose size is the length of the 
write; DosWrite automatically encodes message lengths in the pipe, 
so applications need not encode this information in the buffer 
being written. 


Writes in blocking mode always write all requested bytes before 
returning. In nonblocking mode, writes return either with all 
bytes written or none written; the latter will occur in certain 
cases where the DosWrite would have to block in order to complete 
the request (e.g., no room in pipe buffer or buffer currently 
being written by another client). 


An attempt to write to a pipe whose other end has been closed wil) 
return with ERROR BROKEN PIPE. 
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2.1.8.6.53 DosWriteAsync - Asynchronous Write to a File: 


Purpose 


Format 


Where 


Returns: 


Remarks 


2.0 Functional Characteristics 


Transfers the specified number of bytes to a handle from a buffer 
location, asynchronously with respect to the requesting process's 
execution. 


Calling Sequence: 


EXTRN DosWriteAsync:FAR 


PUSH WORD FileHandle ; Flie handle 

PUSH@ DWORD RamSemaphore ; Address of Ram semaphore 
PUSH@® WORD ReturnCode ¢ Address of 1/0 error RC 
PUSH@ OTHER BufferArea ; Address of user buffer 
PUSH WORD BufferLength 3; Buffer length 

PUSHE WORD yleoeWritten ; Byles written 

CALL DosWriteAsync 


FileHandle is the 2-byte file handle obtained from DoasOpen. 


RamSemaphore is used by the system to post operation complete to 


the caller. 
the system returns the 1/0 operation return 


ReturnCode is where 


code. 
BufferArea is address of the output buffer. 
BufferLength is the number of bytes to be written. 


BytesWritten is where the returns the number of bytes 


written. 


system 


AX «= O ReturnCode « Error code if error 


Error Codes: 


# ERROR _INVALID_HANDLE - the handle is not in use or is 


attached to a physical device. 


* ERROR LOCK VIOLATION - the region of the file is partially 
or completely locked by another process. 


* ERROR ACCESS DENIED - the file is opened as read-only. 


*  Pevice-driver/device-manager errors listed “----<-- ----- 
Sesee Sesse. Sass" “on page --~. 
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Upon return from this function, BytesWritten is the number of 


bytes actually written. 


A BufferLength value of zero is not considered an error. 
case when the value of BufferLength is 
the request as a null operation. 


In the 
zero, the system treats 


RamSemaphore must be set by the application before’ the 
DosWriteAsync cal) is made. The application issues the following 
sequence: 

* DosSemSet. ee 


* DosWriteAsync ... 


" DosSemWait ioe 


Writes bytes or messages toa pipe. Each write 
to a message pipe writes a message whose size is the length of the 
write; DosWrite automatically encodes message lengths in the pipe, 
so applications need not encode this information in the buffer 
being written. 


Writes in blocking mode always write all requested bytes before 
returning. In nonblocking mode, writes return either with all 
bytes written or none written; the latter will occur in certain 
cases where the DosWrite would have to block in order to complete 
the request (e.g., no room in pipe buffer or buffer currently 
being written by another client). 


An attempt to write to a pipe whose other end has been closed wil! 
return with ERROR_BROKEN PIPE. 


2.1.8.7 FSD System Interfaces 


2.1.8.8 Overview of Installable File System Driver Dispatch 


Notes: 


Installable file system entry points are called by the kerne! as a result of 
action taken through the published standard file 1/0 application programming 
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interface in the 1.2 version of the OS/2 Operating System and Utilities 
Functional Specification. 


Installable file systems will be installed as OS/2 dynamic link library 
modules. Unlike device drivers, they may include any number of segments, 
all of which will remain after initialization unless the FSD itself takes 
some action to free them. 


An FSD will export FS entries to the kernel using standard public 
declarations. Each FS entry will be called directly. The kernel will 
manage the association between interna] data structures and FSDs. 


When a {lle system service is required, OS/2 will assemble an argument list, 
and call the appropriate FS entry for the relevant FSD. If a back-level FSD 
{s lvaded, the kerne) will assure that a1] arguments passed and all 
structures passed are understood by the FSD. 


Application program interfaces that are unsupported by an FSD, must receive 
ERROR UNSUPPORTED FUNCTION from the FSD. 


may provide no processing, because 


Certain routines, i.e., FS _PROCESSNAME, 
The 


1) no processing is needed, or 2) processing does not make sense. 
routines should return no error, not ERROR NOT_SUPPORTED. 


2.1.8.9 Data Structures 


As mentioned previously, OS/2 data structures will need to be expanded to 
include a pointer to the file system driver. The affected structures 
include the CDS (current directory structure), the SET (system file table 
entry), the VPB (volume parameter block), and the file search structures. 
In addition, these structures need to include areas which are defined to be 


file system specific. 


routines will generally be passed pointers to two 
areas in addition to read-only parameters which will be specific 
to each call. The FSD does not need to verify these pointers. The two 
parameter areas will contain file system independent data which are 
maintained jointly by the OS/2 andthe file system driver and an area of 
file system dependent data which will be unused by OS/2 and which may be 
used in any way the file system driver wishes. The file system driver is 
generally permitted to use the file system dependent information in any way 
it sees fits it may contain all the information needed to describe the 
current state of the file or directory, or it may contain a ‘handle’ which 
will direct it to other information about the file maintained within the 
FSD. Any handles must be GDT selectors as any SFT, CDS, or VPB may be seen 
by more than one process. 


The file 
parameter 


system service 
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The following definitions are used inthe file system service routine 
definitions in the following section for the file system dependent and file 
system independent parameter areas. 


Disk media and file system layout are described by the following structures. 
The data which are provided to the file system may depend on the level of 
file system support provided by the device driver attached to the block 
device. These structures are relevant only for local file systems. 


/* file system independent - volume params */ 

struct vpfsi { 
unsigned long vpi_vid; /* 32 bit volume ID */ 
unsigned long vpi_hDEV; /* handle to device driver */ 
unsigned short vpi_ bsize; /* sector size in bytes */ 
unsigned long vpi_totsec; /* total number of sectors */ 
unsigned short vpi trksec; /* sectors / track */ 
unsigned short vpi_nhead; /* number of heads */ 
char vpi_text[{12);  /* asciiz volume name */ 


be /* vpfsi */ 


/* file system dependent - volume params */ 

struct vpfsd { 
char 

}: /* vpfsd */ 


vpd_work [36]; /* work area */ 


Per-disk current directories are described by the following structures. 
These structures can only be modified by the FSD during FS_ATTACH and 
FS _CHDIR operations. 


/* file system independent - current dirs */ 
struct cdfsi { 

unsigned short cdi hVPB; /* VPB handle for associated device */ 
unsigned short cdi end; /* offset to root of path */ 
char cdi flags; /* fs independent flags */ 
char edi_curdir[MAX]); /* text of current directory */ 


}: /* cdfsi */ 


/* file system dependent - current dirs */ 

struct cdfsd [{ 
char 

}3 /* edfsd */ 


cdd_work (8); /* work area */ 


Open files are described by data initialized at file open time and discarded 
at the time of last close of all file handles which had been associated with 
that open instance of that file. There may be multiple open file references 
to the same .file at any one time. 
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FSOs are required to suppoct direct access opens. These are indicated by a 
bit set in the sffsi.ef! mode Eleld. /* Eile system independent - file search parameters */ 
@truct fsfai { 

unsigned short fai hvpb; /* volume info. */ 


bs; /* fsfei */ 


/* Elle system independent - file Instance */ 


struct sffsi { e /* file system dependent - file search parameters */ 
unsigned long sfi mode; /* access/sharing mode */ ® atruct fsefsd { 
unsigned short sf$ hVPB; /* volume info. */ l char fsd_ work (24); /* work area */ 
& 


unsigned short sfi_ctime; /* file creation time */ }: /* fsfsd */ 
unsigned short sfi_cdate; /* (lle creation date */ 


unsigned short sf} atime; /* file access time °/ 


unsigned short sti adete; /* Eile access date */ Existing file systems that contorm to the Standard Application Program 
unsigned short sfi miime; /* Eile modification time */ Intecface (Standard AP1} described inthis section, may nol necessarily 
unsigned short sfi mdate; /* {lle modification date */ support al) the described information kept on a file basis. When such Is 
unsigned long sti size; /* size of file */ the case, flle system drivers are required to return to the application a 
unsiqned long sfi position; /* cead/wiite pointer *%/ null (zero) value for the unsupported parameter (when the unsupported data 
/* tha following may be of use in shacing checks */ are oa subset of the data returned by the API) or to return 
unsigned short sfi Vid; /* user 10 of initial opener */ ERXROH NOT SUPPORTED (when all of the data returned by the AP1 is 
unsigned short sf} PID; /* process 1D of initial opener */ unsupported). 2 
unsigned short sf! PDH; /* POB {in 3.x box) of initial opener */ 
unsigned short sf1 sulfsfn;/* system file number of (ile instance */ 
unsigned char sfi tstamp; /* time stamps flays */ 1 2.3.8.9.1 Time Stamping: 
unsigned short sfi type; /* type of object opened */ 
bs /* sf{fs1 */ } All time stamps on files are stamp and propagated to other SFT when the tile 
i is closed or commited (flushed). If a file is opened at time i, written at 
/* tile system dependent - file inatance */ | time 2, and closed at time 3, the last write time wil} become time 3. 
sicuct sff{sd { 
char sfd work{30}; /* work area */ |) Subdirectories only have creation time stamps. 


sO /* effsd 8/ 
} The sfi_ tstamp field contains six flags: 


The Program Data Block of program header, PDH (afi pdb), is the unit of} ST_SCREAT EQU 1 3 stamp creation time 

shating foc 3.X Box processes. For protect mode processes, the unit off] ST _PCREAT EQU 2 3 propagate creation time 

sharing is the Process ID, PID (sf1 pid}. FSOs should use the combination} ST_SWRITE EQU 4 ¢ stamp last write time 

<PDB, PIO, UID> as indicating a distinct process. ‘ ST_PWRITE EQU & 3 propagate last write time 
t ST_SREAD £QU 16 s stamp last read time 

The following data structures are the file system independent and dependent }| ST_PREAD EQu 32 3 propagate last read time 


search records. 
1 These flags are cleared when an SET is created, and some of them may 
| eveutually be set by a file system worker. They are examined when the file 
| 1a closed or flushed. For each time atamps, there are three meaningfu! 
i 


actions: N 
| ST Sxuxx ST_Pxuxx action 
j FeC@ene2e 22 e eee eo @38= ee e@eaaertaewn ena 
1 clear clear don’t do anything 
j set set stamp and propagate (to other SET and disk) 
| clear set don’t stamp, but propagate existing value 
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2.1.8.10 FSD calling conventions and requirements 


Calling conventions between FS router, FSD, and FS helpers are; 
* Arguments will be pushed in left-to-right order onto the stack. 
* The callee is responsible for cleaning up the stack. 


* Registers DS, SI, DI, BP, SS, SP are preserved. 


convention that AX == QO 
indicates an error with the 


with the 
t= 0 


AX 
AX 


® Return conditions appear in 
indicates successful completion. 
value of AX being the error code. 


be enabled and the direction flag should be presumed 


Interrupts must ALWAYS 
flag at. 


to be undefined; calls to the FS helpers will change the direction 
will. 


In 0OS/2, file system drivers will always be called in kernel protect mode. 
This has the advantage of allowing the FSD to execute code without having to 
account for preemption; no preemption occurs when in kernel mode. While 
this greatly simplifies FSD structure, it forces the FSD to yield the CPU 
when executing long segments of code. In particular, an FSD must not hold 
the CPU for more than 2 milliseconds at a atretch. The FSD helper FSH_YIELD 
is provided so that FSDs may relinquish the CPU. 


The file system drivers cannot have any interrupt time activations. Since 
they occupy high, movable, and swappable memory, there is no guarantee upon 
addressability of the memory at interrupt time. 


Each FS service routine may block. 


2.1.8.11 Error codes 


The FSD should use existing error codes when possible. New error codes must 
reserved for FSDs. The FS_FSCTL interface must support 


returning information about new error codes. 


set of error codes for errors general to all FSDs is OxZE00 ~ OxEEFF. 


following errors have been defined: 


The 
The 


The FSD did not recognize the 


* ERROR VOLUME NOT MOUNTED = OxEZE00 - 


volume. 
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| The set of error codes which are defined by each FSD are OxEFOO - OXxFEFF. 
2.1.8.11.1 FS service routine command names: 
The following table summarizes the commands associated with each FS entry 


point, and lists the names the FSD must use to export them. Note that names 
must be in all upper case as required by 0S/2 naming convention. 


LNYD 
00120- 
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FS entry point 


FS ATTACH 

FS CHDIR 

FS CHGPILEPTR 

FS CLOSE 

FS COMMIT 

FS COPY 

FS DELETE 

KS EXIT 

FS FILEATTRIBUTE 
FS FILEINFO 

FS FILE10 

FS FINDCLOSE 

FS FINDFIRST 

FS _FINDFROMNAME 
FS FINDNEXT 
FS_FINDNOTIFYCLOSE 


FS FINDNOTIFYFIRST 


FS_FINDNOTIFYNEXT 
FS FLUSHBUF 
FS_FSCTL 

FS FSINFO 

FS INIT 
FS_IOCTL 

FS MKDIR 

FS MOVE 

FS MOUNT 

FS NEWSI2E 

FS NMPIPE 

FS OPENCREATE 
FS PATHINFO 

FS PROCESSNAME 
FS READ 

FS RMDIR 

FS SETSWAP 

FS SHUTDOWN 

FS WRITE 


The following OS/2 file system API routines are implemented entirely in OS/2 
services from the FSD: DOSDUPHANDLE, 
DOSQHANDTYPE, DOSQVERIFY, DOSSCANENV, 

DOSSELECTDISK, DOSSETFHANDSTATE, DOSSETMAXFH, and DOSSETVERIFY. 


and do not need any 


DOSQFHANDSTATE, 
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OS/2 API supported 


DOSOFSATTACH, DOSFSATTACH 
DOSCHDIR, DOSQCURDIR 
DOSCHGF ILEPTR 

DOSCLOSE 

DOSBUFRESET, DOSCLOSE 
DOSCOPY 

DOSDELETE 

DOSEXIT 

DOSQFILEMODE, DOSSETE IE LEMODE 
DOSQFILEINFO, DOSSETFILEINFO 
DOSFILEIO, DOSFILELOCKS 
DOSF INDCLOSE 

DOSFINDFIRST 

DOSF INDNEXT 

DOSF INDNOT IF YCLOSE 
DOSFINDNOTIFYFIRST 

DOSF INDNOTIFYNEXT 
DOSBUFRESET 

DOSFSCTL 

DOSQFSINFO, DOSSETFSINFO 
DOSDEVIOCTL 

DOSMKDIR 

DOSMOVE 


DOSNEWSIZE 


DOSOPEN 

DOSQPATHINFO, DOSSETPATHINFO 
DOS TREAD 

DOSRMDIR 

DOSSHUTDOWN 

DOSIWRITE 


2.1.8.11.2 FS Entry Point Descriptions: 


Each FS entry point 
parameters needed by that particular entry. 


has a distinct parameter List 
Parameters include: 


2.0 Functional Characteristics 


DOSQCURDISK, 
DOSSEARCHPATH, 


composed of those 
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* File pathnames 

* Current disk/directory information 

* Open file information 

* Application data buffers 

* Descriptions of file extended attributes 


* Other parameters specific to an individual call 


Most of the FS entry points have a level parameter for specifying the level 
of information they are provided or have to supply. FSDs must provide for 
additional levels which may be added in future versions of OS/2. 


File system drivers which support hlerarchical directory structures must use 
*"\’ and ’/' as path name component separators. File system drivers which do 
not support hierarchical directory structures must reject as illegal any use 
of ‘\’ or '/' in path names. The file names ‘°.’ and ‘..’ are reserved for 
use in hierarchical directory structures for the current directory and the 
parent of the current directory respectively. 


Unless otherwise specified in the descriptions below, data buffers may be 
accessed without concern for the accessibility of the data. In other words, 
OS/2 will either check buffers for accessibility and lock them, or transfer 
them into locally accessible data areas. 


Simple parameters will be verified by the IFS router before the FS service 
routine is called. 
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2.1.8.11.3 FS_ATTACH - Attach or Detach An FSD To A Drive or Device: | 
i 
Purpose Attach or detach a remote drive or pseudo-device to an FSD. l 
i 
| 


Remote Drive: 


int far pascal FS_ATTACH (flag, pDev, pvpfsd, pcdfsd, pParm, pLen) 
unsigned short flag; 

char far * pDev; 

struct vpfsd far * pvpfsd; 

struct cdfsd far * pcdfsd; 

char far * pParm; 

unsigned short fac * pLen; 


l 

| 

t 

| 

l 

| 

| 

| 

Pseudo-device: { 
| 

int far pascal FS_ATTACH (flag, pDev, pNull, pDevinfo, pParm, pLen}| 

l 
{ 
j 
l 
I 


unsigned short flag; 
char far * pDev; 
null ptr (OL) pNull; 
unsigned long far * pDevIinfo; 
char far * pParm; 


unsigned short far * pLen; 


Where 
l 
flag indicates attach vs detach. { 
l 
i 


flag == 0O requests an attach. The FSD is being 
called to attach a specified drive or character 
device. 


flag == 1 requests a detach. 


flag == 2 requests the FSD to £111 in the specified 
buffer with attachment information. | 


pDev pointer to the asciiz text of either the drive 
(drive-letter followed by a colon) or to the character 
device (must be \DEV\device) that is being 
attached/detached/queried. The FSD does not need to 
verify this pointer. 


pypfsd/pNull pointer to structure of file-system dependent volume 
parameter information. When an attach/detach/query of a 
character device is requested, this pointer is null. 
When attaching a drive, this structure contains no data 
and 1s available for the FSD to store information needed 
to manage the remote drive. All subsequent FSD callsi| 
have access to the hVPB in one of the structures passed} | 
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in, so the FSD has access to this structure via the use 
of FSH GetVolParms. This structure will have § its 
contents as the FSD had left them. When detaching or 
querying a drive, this structure contains the data as 
the FSD left them. 


pedfsd/pDevinfo pointer to structure of file-system dependent 


pParm 


pLen 


working directory information for drives. When 
attaching a drive, this structure contains no data and 
is avallable for the FSD to store information needed to 
manage the working directory. All subsequent FSD calls 
(generated by API calls that reference this drive) are 
passed a pointer to this structure with contents left as 
the FSD left them. When detaching or querying a drive, 
this structure contains the data as the FSD left them. 
For character devices, pDevinfo points to a DWORD. When 
a device is attached, the DWORD contains no data, and 
can be used by the FSD to store a reference to identify 
the device later on during FS_OpenCreate, when it is 
passed in to the FSD. When detaching or querying the 
device, this DWORD contains the data as the FSD left 
them. 


address of application parameter area. Addressing of 
this data area has not been validated by the kernel (See 
FSH _PROBEBUF). When an attach is requested this wil! 
point to the API~-specified user data block that contains 
information regarding the attach operation = (e.g. 
passwords). For a query, the kernel will £111 in part 
of the buffer, adjust the pointer, and call the FSD to 
fill in the rest. (See structure returned by 
DosQFsAttach, pParm will point to cbFSAData, the FS) 
should fill in cbFSAData and rgFSAData.) pParm must be 
verified, even in the query case. 


pointer to length of the applicaton parameter area. For 
attach, this points to the length of the applicaton data 
buffer. For query, this is the length of the remaining 
space in the application data buffer. Upon filling in 
the buffer, the FSD will set this to the length of the 
data returned. If the data returned is longer than the 
data buffer length, the FSD should set this value’ to be 
the length of the data that query could return. In this 
case, the FSD should also return ERROR_BUFFER_OVERFLOW. 
The FSD does not need to verify this pointer. 


Remarks Local FSDs will never get called with attempts to attach or detach 
drives or queries about drives. 
For remote FSDs called to do a detach, the kernel does not do any 
checking to see if there are any open references on the drive 
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(e.g. open or search references). It is entirely up to the FSD to] 2.1.8.11.4 FS _CHDIR - Change/Verify Directory Path: 
decide whether it should allow the detach operation or not. 
Needless to say, this is not the normal thing to do. Purpose Change or verify the directory path for the requesting process. 


int far pascal FS CHDIR (flag, pedfsi, pcedfsd, pDir, 
iCurDirEnd) 

unsigned short flag; 

struct cdfsi far * pcedfsi; 

struct cdfsd far * pcdfsd; 

char far * pDir; 

unsigned short iCurDirEnd; 


Where 
flag indicates what action is to be taken on the directory. 


flag «<= 0 indicates that an explicit 
directory-change request has been made. 


flag =~ 1 indicates that the working directory need 
to be verified. 


flag == 2 indicates that this reference to a 
directory is being freed. 


* The flag passed to the FSD will have a valid value. 


pedfsi pointer to file-system independent working directory 

structure. For flag == 0, this pointer points to the 

previous current directory on the drive. For flag == 1, 

this pointer points to the most-recent working directory 

on the drive. The cdi_curdir field contains the text of 

the directory that is to be verified. For flag == 2, 

* this pointer is null. The FSD MUST NEVER modify the 
a cdfsi. The kernel handles all updates. 


pcdfsd pointer to file-system dependent working directory 
structure. This is a place for the FSD to store 
information about the working directory. For flag == 0 
or 1, this is the information left there by the ESD. 
The FSD is expected to update this information if the 
directory exists. For flag == 2, this is the 
information left there by the FSD. 


pDir pointer to directory text. For flag == 0, this is the 
a pointer to the directory. For flag == 1 or flag == 2, 
* ; this pointer is null. The FSD does not need to verify 
* this pointer. 


* iCurDirEnd index of the end of the current directory in pDir. 
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This is used to optimize 
iCurDirEnd == -1 there 
to the directory text, i.e. a 
only has meaning for flag == Q. 


device. This 


directory requests to the FSD. 
any information in the cdfsd four a 
conditions, the 
and builds one from scratch when It is needed. 
where a validate cds fails, and the kernel 
and zeroes out the cdisd. This CDS is saved and is 
later.) 


root directory. 


The following is information about the exact state of the 


and cdfsd passed to the FSD for each flag 
about what an FSD should do upon receiving an FS_CHDIR call. 


/* Set new Current Directory */ 


pedfsi, pcdfsd = copy of CDS we’re starting from; maybe useful 
as useful as starting point for verification. 


cdfsi contents: 


- handle of Volume Parameter Block mapped to this 
drive 


hVPB 


end - end of ‘’root’ portion of CurDir 

flags - various flags (indicating state of cdfsd) 
IsValid ~ cdfsd is unknown format (ignore contents) 

IsValid == 0x80 


~ cdfsd is meaningless if CurDir = root 
(mot kept) 


IsRoot 


IsRoot == 0x40 


IsCurrent - cdfsd is known format, but may not be 
current (medium may have been changed) 


IsCurrent == 0x20 


text - Current Directory Text 
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FSD path processing. 
is no current directory relevant 
Parameter 


If 


Remarks The FSD should cache no information when the directory is the 
root. Root directories are a special case. They always exist, 
and never need validation. The kernel does not pass root 


And an FSD is not allowed to cache 
Under normal 
kernel does not save the CDS for a root directory 

( One exception is 
sets it to the root, 
cleaned up 


cdfsi 
value and guidelines 
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icurdir = if Current Directory is in the path of the the new 
Current Directory, this is the index to the end of 
the Current Directory. If not, then this = -1 (Current 
Directory does not apply). 


pDir = path to verify as legal directory. 


DO THIS 


ana eee ae 


Validate path named in pDir. 
/* This means both that it exists AND that it’s a dir. 
pedfsi, pedfsd, icurdir give old CDS, which may allow 
optimization a | 


if (Validate succeeds) { 
If (pDir != ROOT) 
store any cache information in area pointed to by 


pedfsd. 
else 
do nothing! 
/* area pointed to by pedfsd will be thrown away, 580 
don’t bother storing into it | */ 
return success 
} 
else 


return failure 
/* Kernel will create new CDS using pDir data and pcdfsd data. 


If the old CDS is valid, the kernel will take care of 
Cleaning it up. 


The FSD MUST NOT edit any structure other than the *pcdfsd 
area, with which it may do as it chooses. s/ 


) /* flag == 0 */ 


/* Validate current CDS structure */ 
pedfsi = pointer to copy of cdfsi of interest. 


pedfsd = pointer to copy of cdfsd. Flags in cdfsi indicate the 
state of this cdfsd. It may be: (1) completely invalid 
(unknown format), (2) known format, but non-current 
information, (3) competely valid, or (4) all zero (root). 


DO THIS 


= ee oe ae ee oe 


Validate that CDS still describes a legal directory (using 
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else if (flag == 2) { 
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cdi text) 


if (valid) { 
update cdfsd if necessary 
return success 
/* kernel will copy cdfsd into real CDS */ 
} 
else { 
if (cdi isvalid) 
release any resources associated with cdfsd 
/* kernel will force Current Directory to root, and 
will zero out cdfsd in real CDS */ 


return fajlure 


) 


/* The FSD MUST NOT modify any structure other than the cdfsd 
pointed to by pcdfsd. a/ 


pcedfsd = pointer to copy of cdfsd of CDS being freed. 


DO THIS 


oe ee ow ee 


Release any resources associated with the CDS. 

/* For example, if cdfsd (where pcdfsd points) contains a 
pointer to some FSD private structure associated with the 
CDS, that structure should be freed. «/ 


/* Kernel will not retain the cdfsd */ 
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2.1.8.11.5 FS CHGFILEPTR - Move a file’s position pointer: 


Purpose 


Where 


Remarks 
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Move a file’s logical read/write position pointer. 


int far pascal FS CHGFILEPTR (psffsi, psffsd, offset, type, 10flag) 
Struct sffsi far * psffsi; 
struct sffsd far * psffsd; 


long offset; 
unsigned short type; 
unsigned short TIOflag; 


psffsi pointer to file-system independent portion of open file 
instance. The FSD uses the current file size or 
sfi position along with offset and type to compute a new 
sfi_ position. This is updated by the system. 

psffsd pointer to file-system dependent portion of open tlle 
instance. The FSD may store or adjust data as 
appropriate in this structure. 


signed offset to be added to the current file size or 
position to form the new position within the file. 


offset 


indicates base of seek operation. 
seek relative to beginning of file. 
seek relative to current position within the file. 
m= 2 indicate seek relative to end of file. 
of type passed to the FSD will be valid. 


type «= 0 indicates 
type == 1 indicates 
type 
The value 


type 


TOflag indicates information about the operation on the handle. 


1O0flag == 0x0010 indicates write-through. 


1Oflag == 0x0020 indicates no-cache. 


The file system may want to take the seek operation as a hint that 
an 1/0 operation is about to take place at the new position and 
initiate a positioning operation on sequential access media or a 
read-ahead operation on other media. 


Some 3xbox programs expect to be able to do a negative seek. 0OS/2 
will pass these requests on to the FSD and will return an error 
for protect mode negative seek requests. Since a seek to a 
negative position is effectively a seek to a very large offset, it 
is suggested that the FSD return end-of-file for subsequent'§ read 
requests. 


0 
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FSDs must allow seeks to positions beyond end-of-file. 


The information passed in I0flag is what was set for the handle 
during a DosOpen/DosOpen2 operation, or by a DosSetFHandState 
call. 
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2.1.8.11.6 FS CLOSE - Close a File: 


Purpose Closes the specified file handle. 
int far pascal FS CLOSE (type, 10flag, psffsi, psffsd) 
unsigned short type; 
unsigned short 1Oflag; 
struct sffsi far * psffsi; 
struct sffed far * psffad; 
Where 
type indicates what type of a close operation this is. 
type == 0 indicates that this is not the final close 
of the file or device. 
type == 1 indicates that is the final close of this 
file or device for this process. 
type == 2 indicates that this is the final close for 
this file or device for the system. 
10flag indicates information about the operation on the handle. 
10flag == 0x0010 indicates write-through. 
10flag == 0x0020 indicates no-cache. 
psffsi pointer to file-system independent portion of open file 
instance. 
psf fad pointer to £file-system dependent portion of open file 
instance. 
Remarks Called on last close of a file. 
Any reserved resources for this instance of the open file may be 
released. It may be assumed that all open files will be closed at 
process termination. That is not to say that this entry point 
will always be called at process termination for any files or 
devices open for the process. 
A close operation should be interpreted by the FSD as meaning that 
the file should be commited to disk as appropriate. 
Of the information passed in 10flag, the write-through bit is a 
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MANDATORY bit in that any data written to the block device must be 
put out on the medium before the device driver returns. The 
no-cache bit, on the other hand, is an advisory bit that says 
whether the data being transferred is worth caching or not. 
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2.1.8.11.7 FS_ COMMIT - Commit a file’s buffers to Disk: 


Purpose Flush requesting process’s cache buffers and update directory 
information for the file handle. 
int far pascal FS COMMIT (type, IOflag, psffsi, psffsd) 
unsigned short type; 
unsigned short I0f lag; 
struct sffsi far * psffsi; 
struct sffsd far * psffsd; 
Where 
type indicates what type of a commit operation this is. 
type == 1 indicates that this is a commit for a 
specific handle. This type is specified if 
FS COMMIT is called for a DosBufReset of specific 
handle. 
type <= 2 indicates that this is a commit due to a 
DosBufReset (-1). 
IOflag indicates information about the operation on the handle. 
I0flag == 0x0010 indicates write-through. 
IO0flag == 0x0020 indicates no-cache. 
psffsi pointer to file-system independent portion of open file 
instance. 
psffsd pointer to file-system dependent portion of open file 
instance. 
Remarks Only called via DosBufReset. OS/2 reserves the right to call 
FS COMMIT even if no changes have been made to the file. 
For DosBufReset (-1), FS COMMIT will be called for each handle the 
calling process has open on the FSD. 
The FSD should update access and modification times, if 
appropriate. 
Any locally cached information about the file must be output to 
the media. The directory entry for the file is to be updated from 
the sffsi and sffsd structures. 
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Since MiniFSDs used to boot IFSs are read-only file systems, they 
need not Support the FS COMMIT call. 


Of the information passed in lOf}ag, the write-through bit is a 
MANDATORY bit in that any data written to the block device must be 
put out on the medium before the device driver ceturns. The 
no-cache bit, on the other hand, Is an advisory bit that says 
whether the data being transferred is worth caching or not. 


The FSD should copy ali suppotted time stamps from the SFT to the 

disk. Beware that the fast read time stamp may need to be written 
to the disk even though the file is clean. After this is done, 
the FSD should clear the sfl tstamp field to avoid having to write 
to the disk again if the user calts commit repealingly without 
changing any of the time stamps. 


If the disk is not writeable and only the last read time stamp has 
changed, the FSD should either issue a warning or Ignore the 
error. This relieves the user trom having to un-protect an FSD 
floppy disk in order to read the files on it. 
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Copy specified file or subdirectory to specified target. 


int far pascal FS_COPY(flag, pcdfsi, pedfsd, 
pSrc, iSrcCurDirEnd, 
pDst, iDstCurDirEnd) 


unsigned short flag; 
Struct cdfsi far * pcedfsi; 
struct cdfsd far * pedfsd; 


char far * pSre; 

unsigned short 4{SrcCurDircEnd; 
char fac * pDst; 

unsigned short {DstCurDirEnd; 
flag bitmask controlling copy 


0x0001 specifies that an existing target file/ 
directory should be replaced (see explanation 
above under DosCopy). 


0x0002 specifies that a source file will be 
appended to the destination file (see explanation 
above under DosCopy). 


All other bits reserved. 


pedfsi Pointer to the file-system independent working director 
structure. : 


pcedfad Pointer to the file-system dependent working directory 
atructure. 


pSrce Pointer to ASC1I2Z name of source file/directory. 

4SecCurDirEnd index of the end of the current directory in pSrc. 
If = -1, there is no current directory relevant to the 
source name. 

pDst Pointer to ASCII2Z name of destination file/directory. 

iDstCurDirEnd index of the end of the current directory in pDst. 


If = -1, there is no current directory relevant to the 
destination name. 


Remarks The file apecified in sourcename should be copied to the 
targetfile if possible. 
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There will be no assurances that the files specified are 
not currently open. File system drivers will have to 
assure consistency of file allocation information and 
directory entries. 


The file system driver should return the special error 
ERROR_CANNOT COPY if it cannot perform the copy because: 


* it doesn’t know how 
" the source and target are on different volumes 


* of any other reason for which it would make 
sense for its caller to perform the copy 
operation manually. 


Returning ERROR_CANNOT COPY indicates to its caller that 
it should attempt to perform the copy operation 
manually; any other error will be returned directly to 
the caller of DOSCOPY. 


FS COPY needs to check that certain types of illegal 
copying operations are not performed. A directory 
cannot be copied to itself or to one of its 
subdirectories. This is especially critical in 
situations where two different fully- qualified 
pathnames can refer to the same file or directory. (For 
example, if X: is redirected to \\SERVER\SHARE, then X 
:\PATH and \\SERVER\SHARE\PATH refer to the same 
object.) 


The behavior of FS COPY should match the behavior of the 
generic DosCopy routine. 


See errors under DOSCOPY for other error codes that can 
be returned. 
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2.1.8.11.9 FS DELETE - Delete a File: 


Purpose 


Where 


*# *@ 2 & 


* Remarks 
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Removes a directory entry associated with a filename. 


int far pascal FS DELETE (pcdfsi, pedfsd, pFile, iCurDirEnd) 
struct cdfsi far * pedfsi; 

struct cdfsd far * pcedfsd; 

char far * pFile; 

unsigned short 4{CurDirEnd; 


pedfsi pointer to file-system independent working directory 
structure. 


pedfsd pointer to file-system dependent working directory 
structure. 


pFile pointer to asciiz name of file/directory. The FSD does 
not need to validate this pointer. 


icurDirEnd index of the end of the current directory in pFile. 
This is used to optimize FSD path processing. It 
4iCurDirEnd == -1 there is no current directory relevant 
to the name text, i.e. a device. 

The file(s) specified in filename should be deleted. 

The deletion of a file opened in compatibility mode in the 3xbox 

by the same process requesting the delete is supported. 0S/2 wil}! 

call FS CLOSE for the file before issuing the call to FS_DELETE. 


The filename may not contain wildcard characters. 
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2.1.8.11.10 FS EXIT - End of process: 

Purpose Release FSD resources still held after process termination. 
void far pascal FS_EX1T (uid, pid, pdb); 
unsigned short uid; 


unsigned short pid; 
unsigned short pdb; 


Where 
uid user id of process. This will be a valid value. 
pid process id of process. This will be a valid value. 
pdb 3x box process id of process. This will bea 
value. 


Remarks This call is not needed to release file resources since all files| 


valid 


are closed on process termination, but it may be helpful if 
resources are being held due to unterminated searches (in the case 


of searches initiated from the 3.x box). 
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2.1.8.11.11 FS_FILEATTRIBUTE - Query/Set File Attribute: 


Purpose Query/set 


int far pascal FS_FILEATTRIBUTE (flag, pedfsi, pcdfsd, 


unsigned short flag; 


struct cdf 


struct cdfsd far * pcdfsd; 


char far * 


unsigned short icurDirEnd; 
unsigned short far * pAttr; 


flag 


pedfsi 


pcedfsd 


pName 
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the attribute of the specified file. 


pName, iCurDirEnd, pAttr) 
si far * pcedfsi; 


pName; 


indicates retrieval of attributes vs setting attributes 
flag == 0 indicates retrieving the attribute. 
flag == 1 indicates setting the attribute. 
All other values reserved. 

The value of flag passed to the FSD will be valid. 


pointer to file-system independent working directory 
structure. 


pointer to file-system dependent working directory 
structure. 


pointer to asciiz name of file/directory. The FSD does 
not need to validate this pointer. ; 


iCurDirEnd index of the end of the current directory in pName. 


pAttr 


This is used to optimize FSD path processing. If 
iCurDirEnd == -1 there is no current directory relevant 
to the name text, i.e. a device. 


pointer to attribute. For flag == 0, the FSD should 
store the attribute in the indicated location. For flag 
== 1, the FSD should retrieve the attribute from this 
location and set it in the file/directory. The FSD does 
not need to validate this pointer. 
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2.1.8.11.12 FS_FILEINFO + Query/Set a File’s Information: 


Purpose 


Returns information for a specific file. 


int far pascal FS FILEINFO (flag, psffsi, psffsd, 


unsigned short 
struct sffsi far * 
struct sffsd far * 
unsigned short 


char far * 


unsigned short 
unsigned short 


Where 


flag 


psffsi 
psffsd 
level 


pData 


cbData 
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level, pData, cbData, IOflag) 
flag; 

psffsi; 

psf fsd; 

level; 

pData; 

cbData; 

10f lag; 


indicates retrieval of information vs setting 


information. 


flag == 0 indicates retrieving information. 


flag == 1 indicates setting information. 


All other values reserved. 
The value of flag passed to the FSD will be valid. 


pointer to file-system independent portion of open file 
instance. 


portion of open file 


pointer to file-system dependent 


instance. 


information level to be returned. Level selects among a 
series of structures of data to be returned. 


address of application data area. Addressing of this 
data area has not been validated by the kernel (See 
FSH _PROBEBUF). When retrieval (flag == 0) 4s specified, 
the FSD will place the information into the buffer. 
When outputting information to a file (flag == 1), the 
FSD will retrieve that data from the application buffer. 


length of the application data area. For flag == 0, 
this is the length of the data the application wishes to 
retrieve. If there is not enough room for the entire 
level of data to be returned, the FSD will return 
ERROR_BUFFER_OVERFLOW. For flag == 1, this is the 
length of data to be applied to the file. 
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I0flag indicates information about the operation on the handle. 


IOflag == 0x0010 indicates write-through. 


IOflag == 0x0020 indicates no-cache. 


If setting time on file, copy new time/date into SFT, then set 
ST_PCREAT, ST_PWRITE, and ST_PREAD but clear ST_SCREAT, ST_SWRITE, 
and ST_SREAD. If querying time on file, simply copy time stamps 
from directory entry into SFT. 


Of the information passed in I0Oflag, the write-through bit is a 
MANDATORY bit in that any data written to the block device must be 
put out on the medium before the device driver returns. The 
no-cache bit, on the other hand, is an advisory bit that says 
whether the data being transferred is worth caching or not. The 
I0flag bit applies to both the data in the file and to the EAs 
attached to the file as well. ? 


The supported information levels are described in the OS/2 1.2 API 
description. 
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2.1.8.11.13 FS_FILEIO - Multi-function File I/0: 


Purpose 


Where 


2.0 Functional Characteristics 


Perform mu 


ltiple lock, unlock, seek, read, and write I/O. 


int far pascal FS FILEIO (psffsi, psffsd, 


struct sffsi far * 
struct sffsd far * 


char far * 


unsigned short 


: pCmdList, cbCmdList, poError, I0flag) 
psffsi; 

psffsd; 

pCmdList; 

cbCmdList; 


unsigned short far * poError; 


unsigned short 


psffsi 
psffsd 


pCmdiist 


10flag; 


pointer to file-system independent portion of open file 


instance. 
pointer to file~system dependent portion of open file 
instance. 


pointer to command list that contains entries indicating 
what commands will be performed. Each individual 
operation (CmdLock, CmdUnlock, CmdSeek, CmdIO) is 
performed as atomic operations until all are complete or 
until one fails. CmdLock executes a multiple range lock 
as an atomic operation. Unlike CmdLock, CmdUnlock 
cannot fail as long as the parameters to it are correct, 
and the calling application had done a Lock earlier, and 
so it can be viewed as atomic. The validity of the user 
address has not been verified (see FSH _PROBEBUF). 


For CmdLock, the command format is: 


CmdLock Struc 


Cmd dw 0 : O for lock operations 
LockCnt dw ? ; Number of locks that follow 
TimeOut dd ? : ms timeout for lock success 


CmdLock Ends 


which is followed by a series of records of the 
following format: 

Lock Struc 

Share dw ? : 0 for exclusive, 1 for read-only ac¢ess 
Start dd ? ¢ start of lock region 

Length dd ? : length of lock region 


Lock Ends 
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If a lock within a CmdLock causes a timeout, none of the 
other locks within the scope of CmdLock are in force 
since the lock operation is viewed as atomic. 


CmdLock.TimeOut is the count in milliseconds, until the 
requesting process is to resume execution if the 
requested locks are not available. If CmdLock.TimeQut == 


0, there will be no wait. If CmdLock.TimeOut < 
OxFFFFFFFF it is the number of milliseconds to wait 
until the requested locks become available. If 


CmdLock.TimeOut == OxXFFFFFFFF then the thread will wait 
indefinitely until the requested locks become avallable. 


Lock.Share defines the type of access other processes 
may have to the file-range being locked. value == 0, 
other processes have ’No-Access’ to the locked range. 
value == 1, other processes have ‘Read-Only’ access to 
the locked range. 


For CmdUnlock, the command format is: 


CmdUnlock Struc 
Cma dw 1 
UnlockCnt dw ? 
CmdUnlock Ends 


1 for unlock operations. 
Number of unlocks that follow 


=e Ya 


which is followed by a series of records of the 


following format: 


UnLock Struc 
Start dd ? 
Length dd ? 
UnLock Ends 


start of locked region 
length of locked region : 


For CmdSeek, the command format is: 


CmdSeek Struc 


Cmd dw ? : 2 for seek operation 
Method dw ? ; O for absolute, 
#1 for relative to current, 
; 2 for relative to EOF. 
Position dd ? 3; file seek position or delta 
Actual dd ? ; actual position seeked to 


CmdSeek Ends 


For CmdIO, the command format is: 


CmdaIo Struc 
Cmd dw 3 for read, 4 for write 
Buffer@ dd ptr to the data buffer 


BufferLen dw 
Actual dw 


number of bytes requested 
number of bytes actually 
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; transferred 


Cmd IO Ends 

cbCmdList length in bytes of the command list. 

poError offset within the command list of the command that 
caused the error. This offset is relative to the 


beginning of the command list. This field only has value 
when an error occurs. The validity of the user address 
has not been verified (see FSH PROBEBUF). 


IOflag indicates information about the operation on the handle. 
IO0flag == 0x0010 indicates write-through. 
IO0flag == 0x0020 indicates no-cache. 

This function provides a simple mechanism for combining the 


following operations into a single request and providing improved 
performance particularly in a networking environment. 


File Systems that do not have the FileIO bit in their FS_ATTRIBUTE 
point will never see this call. The command list will be parsed 
by the IFS router; the FSD will see only FS _CHGFILEPTR, FS_ READ, 
FS WRITE calls. 


File systems that have the FileIO bit in their attribute field 
will see this cali in its entirety. The atomicity guarantee 
applies only to the commands themselves and not to the list as a 
whole. 


Of the information passed in I0flag, the write-through bit is a 
MANDATORY bit in that any data written to the block device must be 


put out on the medium before the device driver returns. The 
no-cache bit, on the other hand, ts an advisory bit that says 
whether the data being transferred is worth caching or not. 
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2.1.8.11.14 FS FINDCLOSE - Directory Read (Search) Close: 


Purpose 


Where 


Remarks 


2.0 Functional Characteristics 


Provides the mechanism for an FSD to release resources allocated 


on behalf of FS _FINDFIRST and FS_FindNext. 


int far pascal FS FINDCLOSE (pfsfsi, pfsfsd) 
Struct fsfsi far * pfsfsi; 
struct fsfsd far * pfsfsd; 


pfsfsi pointer to § file-system independent file search 
structure. The FSD should not update this structure. 
pfsfsd pointer to  file-system independent file search 


structure. The FSD may use this to. store information 


about continuation of the search. 


DOSFINDCLOSE has 
search buffer. 
released. 


been called on the handle associated with the 
Any file system related information may be 


If FS _FINDFIRST for a particular search returns 
FS FINDCLOSE for that search will not be issued. 


an error, an 
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2.1.8.11.15 FS_FINDFIRST - Find First Matching File Name: | pfsfsi pointer to file-system independent file search 
| structure. The FSD should not update this structure. 
* Purpose Find first occurrence of a file name in a directory. 
| pfsfsd pointer to  file-system independent file search 
[ Structure. The FSD may use this to store information 


* int far pascal FS FINDFIRST (pcdfsi, pcdfsd, pName, iCurDirEnd, | about continuation of the search. 
* attr, pfsfsi, pfsfsd, 
* pData, cbData, pcMatch, pData address of application data area. Addressing of this 
* level, flags ) data area has not been validated by the kernel (See 
struct cdfsi far * pcdfsi; FSH PROBEBUF). The FSD will £111 in this area with a 
. struct cdfsd far * pcdfsd; set of packed, variable~length structures that contain 
. char far * pName; the requested data and matching file names. 
* unsigned short {CurDirEnd; 
* unsigned short attr; cbData length of the application data area in bytes. 
* struct fsfsi far * pfisfsi; 
* struct fsfsd far * pfsfsd; peMatch pointer to number of matching entries. The FSD will 
* char far * pData; return at most this number of entries. The FSD will 
* unsigned short cbData; * store into it the number of entries actually placed in 
* unsigned short far * pcMatch; * the data area. The FSD does not need to validate this 
® unsigned short level; * pointer. 
| unsigned short flags; 
bs level information level to be returned. Level selects among a 
* series of structures of data to be returned. The level 
Where * passed to the FSD will be valid. 
pedfsi pointer to file-system independent working directoryj| flags indicates whether to return file position information. 
structure. 
| flags == 0 indicates that file position information 
pcdfsd pointer to file-system dependent working directory}i should not be returned and the information format 
structure. | described under DosFindFirst should be used. 
pName pointer to asciiz name of file/directory. Wildcard} | flags == 1 indicates that file position information 
characters are allowed only in the last component. The|{ should be returned and the information format 
FSD does not need to validate this pointer. ; described below should be used. the flag passed to 
] the FSD will have a valid value. 
iCurDirEnd index of the end of the current directory in pName. 
This is used to optimize FSD path processing. If 
iCurDirEnd == -] there is no current directory relevant 
to the name text, i.e. a device. * Remarks 
attr bit field that governs the match. Any directory entry]! For flags == 1, the FSD must store in the first dword of the 
whose attribute bit mask is a subset of attr and whose]] per-file attributes structure adequate information to allow the 
name matches that in pName should be returned. For|| search to be resumed from the file be calling FS_FINDFROMNAME. 
example, an attribute of system and hidden is passed in./}| For example, an ordinal representing the file’s position in the 
A file with the same name and an attribute of system is}| directory could be stored. If the filename must be used to 
found. This file should be returned. A file with the]| restart the search, the dword may be left blank. 
same name and no attributes (a regular file) would also 
be returned. The attributes read-only and file archive} | For level 0x0001 and flags == 0, directory information for 
will not be passed in and should be ignored when|{ FS FINDFIRST (find record) is returned in the following format: 
comparing directory attributes. The value of attr] 
| passed to the FSD will be valid. 
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Struct { 
unsigned short dataCreate; 
unsigned short timeCreate; 
unsigned short dateAccess; 
unsigned short timeAccess; 
unsigned short dateWrite; 
unsigned short timeWrite; 
long cbEOF ; 
long cbhAlloc; 
unsigned short attr; 
unsigned char cbName; 
unsigned char szName[); 


For level 0x0001 and flags == 1, directory information for 
FS FINDFIRST (find record) is returned in the following format: 


struct { 
long position; 
unsigned short dataCreate; 
unsigned short timeCreate; 
unsigned short dateAccess; 
unsigned short timeAccess; 
unsigned short dateWrite; 
unsigned short timeWrite; 
long cbEOF ; 
long cbAlloc; 
unsigned short attr; 
unsigned char cbName; 
unsigned char szName[J; 


The other information levels have similar format, with the 
position the first field in the structure for flags == 1. 


If FS _FINDFIRST for a particular search returns an error, an 
FS FINDCLOSE for that search wil] not be issued. 


Sufficient information to find the next matching directory entry 

must be saved in the fsfsd structure. 

In the case where direcotyr entry informaiton overflows the pData 

area, the FSD should be able to continue the search from the entry 

which caused the overflow on the next FS _FINDNEXT or 

FS _FINDFROMNAME. . 

In the case of a global search ina directory, the first two 

entries in that directory as reported by FSD should be ‘.’ and 
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} 2.1.8.11.16 FS_PINDFROMNAME - Find Matching File Name Starting from Name: 


| Purpose 


Where 


Find occurrence of a 


file name ina directory beginning from 


position or pName. 


int far pasca] FS _FINDFROMNAME (pfsfsi, pfsfsd, pData, cbData, 


struct fsfsi far * 
struct fsfsd far * 


char far 
unsigned 
unsigned 
unsigned 
unsigned 
char far 
unsigned 


pfsfsi 


pf:tsd 


pData 


cbData 


pcMatch 


level 


position 


pName 
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pcMatch, position, pName) 

pfsfsi; 

pfsfsd; 
- pData; 
short cbData; 
short far * pcMatch; 
short level; 
long position; 
* pName; 
short flags; 
pointer to file-system independent file search 
structure. The FSD should not update this structure. 
pointer to file-system dependent file search structure. 
The FSD may use this to. store information about 
continuation of the search. 
address of application data area. Addressing of this 
data area has not been validated by the kernel (See 
FSH PROBEBUF). The FSD will fill in this area with a 
set of packed, variable-length structures that contain 


the requested data and matching file names in the format 
required for DosFindFirst/Next. 


length of the application data area in bytes. 


pointer to number of matching entries. The FSD will 
return at most this number of entries. The FSD will 
store into it the number of entries actually placed in 


the data area. The FSD does not need to validate this 


pointer. 


information level to be returned. Level selects among a 


series of structures of data to be returned. The level 
passed to the FSD will] be valid. 

the file-system specific information about where to 
restart the search from. This information was returned 
by the FSD in the ResultBuf for a 


DosFindFirst2/Next/FromName call. 


is the filename to from which to continue the search. 
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The FSD does not need to validate this pointer. 


indicates whether to return file position information. 
The flag passed to the FSD will have a valid value. 


flags 


The FSD may use either the position or filename to determine the 
position from which to resume the directory search. So _ the Fsp 
need not return position if it uses name and vice versa. 


For flags == 1, the FSD must store in the position field adequate 
information to allow the search to be resumed from the file by 
calling FS_FINDFROMNAME. See FS FINDFIRST for a description of the 
data format. 


The FSD must ensure that enough information is stored in the fsfsd 
structure to enable it to continue the search. 
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2.1.8.11.17 FS_PINDNEXT - Find Next Matching File Name: 


* Purpose Find next occurrence of a file name in a directory. 
s int far pascal FS FINDNEXT (pfsfsi, pfsfsd, pData, cbData, pcMatch 
| level, flags) 
s struct fsfsi far * pfsfsi; 
* struct fsfsd far * pfsfsd; 
char far * pData; 
unsigned short cbData; 
unsigned short far * pcMatch; 
| unsigned short level; 
| unsigned short flags; 
Where 
| pfsfsi pointer to file-system independent file search 
t structure. The FSD should not update this structure. 
| pfstsd pointer to file-system dependent file search structure. 
1 The FSD may use this to store information about 
| continuation of the search. 
pData address of application data area. Addressing of this 
data area has not been validated by the kernel (See 
FSH PROBEBUF}). The FSD will fi11 in this area with a 
set of packed, variable-length structures that contain 
the requested data and matching file names. 
cbData length of the application data area in bytes. 
pcMatch pointer to number of ' matching entries. The FSD will 
return at most this number of entries. The FSD will 
* store into it the number of entries actually placed in 
" the data area. The FSD does not need to validate this 
* pointer. 
| level information level to be returned. Level selects among a 
| series of structures of data to be returned. The level 
| passed to the FSD will be valid. 
{ flags indicates whether to return file position information. 
| Remarks For flags == 1, the FSD must store in the position field adequate 
j information to allow the search to be resumed from the file be 
( calling FS _FINDFROMNAME. See FS_FINDFIRST for a description of 
| the data format. 
| The leve] passed to FS FINDNEXT will be the same level as that 
| passed to FS FINDFIRST to initiate the search. 
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Sufficient information to find the next matching directory entry 
must be saved in the fsfsd structure. 


The FSD should take care of the case where the pData are overflow 
may occur. FSD should be able to start the search from the same 


entry for the next FS _FINDNEXT as the one for which the overflow 
occurred. 

In the case of a global search in a directory, the first two 
entries in that directory as reported by FSD should be ‘°.’ and 


‘..’ (the current and the parent directories). 
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2.1.8.11.18 FS_FINDNOTIFYCLOSE ~- Close Find-Notify Handle: 2.1.8.11.19 FS FINDNOTIFYFIRST - Start monitoring directory for changes: 


Purpose Closes the association between a 'Find-Notify’ handle and a] Purpose’ Start monitoring a directory for changes. 
DOSFINDNOTIFYFIRST or DOSFINDNOTIFYNEXT function. Provides the 
mechanism for an FSD to release resources allocated on behalf of 
FS FINDNOTIFYFIRST and FS FINDNOTIFYNEXT. int far pascal FS _FINDNOTIFYFIRST (pcedfsi, pedfsd, pName, iCurDirEnt, 





. attr, pHandle, 
* pData, cbData, pcMatch, 
int far pascal FS_FINDNOTIFYCLOSE (handle) ® level, timeout) 
unsigned short handle; ® struct cdfsi far * pcedfsi; 
& struct cdfsd far * pcdfsd; 
* char far * pName; 
Where ® unsigned short iCurDirEnd; 
* unsigned short attr; 
handle directory handle. This handle was returned by the FSD]* unsigned short far * pHandle; 
and is associated with a previous FS_FINDNOTIFYFIRST or char far * pData; ‘ 
FS FINDNOTIFYNEXT call. unsigned short cbData; 
) unsigned short far * pcMatch; 
| unsigned short level; 
Remarks FS _FINDNOTIFYCLOSE has been called on the handle associated with a unsigned long timeout; 
FS FINDNOTIFYFIRST. Any file system related information may be 
released. 
Where 
pedfsi pointer to file-system independent working directory 
structure. 
pcedfsd pointer to file-system dependent working directory 
structure. 
pName pointer to asciiz name of file/directory. Wildcard 
* characters are allowed only in the last component. The 
* FSD does not need to verify this pointer. 
* iCurDirEnd index of the end of the current directory in pName. 
* This is used to optimize FSD path processing. If 
* iCurDirEnd == -1 there is no current directory relevant 
* to the name text, i.e. a device. 
* attr bit field that governs the match. Any directory entry 
” whose attribute bit mask is a subset of attr and whose 
* name matches that in pName should be returned. See 
* FS FINDFIRST for explanation. 
* pHandle pointer to directory handle. The FSD must allocate a 
* handle for the directory monitoring continuation 
* information and store it here. This handle will be 
* passed to FS FINDNOTIFYNEXT to continue directory 
t monitoring. The FSD does not need to verify this 
& pointer. 
pData address of application data area. Addressing of this 
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data area has not been validated by the kernel (See{ 2.1.8.113.20 €S FINDNOTIFYNEXT - Resume reporting directory changes: 
FSH PROBEHUS). The FSD will f11!1 in this acea with a 


set of packed, variable-length structures that contain} Purpose Resume reporting of directory or file changes. 
the requested data and matching file names. 





cbhData length of the application data area in bytes. ® int far pascal FS _FINDNOTIFYNEXT (handle, pData, cbhData, pcMatch, 
level, timeout) 
peMatch pointer to number of matching entries. The FSD will}* unsigned short handle; 
return aC most this number of entries. The FSD wil) char far * pData; 
store into it the number of entries actually placed in unsigned short cbhData; 
the data area. The FSD does not need to verify this unsigned short far * pcMatch; 
pointer. ] unsigned short level; 
unsigned long timeout ; 
level information level to be returned. Level selects among a 
Series of steuctuces of data to be returned. See 
DOSFINDNOTIFYFIKST tor information. The level passed to] Where 
the FSD will be valid. 
: handle directory handle. This handle was returned by the FSD 
timeout millisecond timeout. The FSD will wait until either the}* and is associated with a previous FS FINDNOTIFYFIRST or 
timeout has expired, the buffer is full, or the]*¢ FS FINDNOTIFYNEXT call. 
specified number of entries returned before returning to 
the caller. pData address of application data area. Addressing of this 
data area has not been validated by the kernel (See 
FSH PROBEBUF). The FSD will £11) in this area with a 
set of packed, variable-length structures that contain 
the cequested data and matching file names. 
cbData length of the application data area in bytes. 
peMatch pointer to number of matching entries. The FSD will 
return at most this number of entries. The FSD wilt 
. atore into it the number of entries actually placed in 
e the data area. The FSD does not need to verify this 
pointec. 
} level information level to be returned. Level selects among a 
( series of structures of data to be returned. See 
{ DOSFINDNOTIFYFIRST for information. The level passed to 
} the FSD will be valid. 
timeout millisecond timeout. The FSD will wait until either the 
timeout has expired, the buffer is full, or the 
specified number of entries returned before returning to 
the caller. 
* Remarks pcMatch is the number of changes required to directories or files 
. that match the pName target and attr specified during a related, 
i previous FS FINDNOTIFYFIRST. The file system uses thia field to 
e return the number of changes that actually occurred since the 
| isaue of the present FS_FINDNOTIFYNEXT. 
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The level passed to FS_FINDNOTIFYNEXT will be the same level as{ 2.1.8.11.21 FS_FLUSHBUF - Commit file buffers: 


that passed to FS_FINDNOTIFYFIRST to initiate the search. 
Purpose Flushes cache buffers for a specific volume. 


int far pascal FS FLUSHBUF (hVPB, flag) 
unsigned short hVPB; 
unsigned short flaq; 


Where 

hVPB handle to volume for flush. 

flag indicator for discarding of cached data. 
flag =< 0 indicates,cached data may be retained. 
flag == 1 indicates the FSD will discard any cached 
data after flushing it to the specified volume. 
All other values reserved. 
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2.1.8.11.22 FS_FSCTL ~ File System Control: * d4ArgType <= 2 means that pArgDat->cd.pcedfsi and 
| " pArgDat~>cd.pcdfsd point to a cdfsi and cdfsd, 
Purpose Allow an extended standard interface between an application and aj* pArgDat->cd.pPath points to a canonical pathname, 
file system driver. * and pArgDat->cd.iCurDirEnd gives the index of the 
. end of the current directory in pPath. The FSD does 
t 


not need to verify the pPath pointer. 
int far pascal FS FSCTL (pArgdat, {ArgType, func, 





pParm, lenParm, plenParmIO, * lArgType = 3 means that the call was FSD name 
pData, lenData, plenDatalI0O) routed, and pArgDat is a NULL pointer. 
union argdat far * pArgDat 
unsigned short iArgType; 
unsigned short func; : func indicator of function to perform. 
char far * pParm; 
unsigned short lenParm; * func == 1 indicates request for new error code 
unsigned short far * plenParml0; + information. 
char far * pData; 
unsigned short lenData; + func == 2indicates request for maximum EA size and 
unsigned short far * plenDatal0O; + EA list size supported. This will be returned in 
+ the buffer pointed to by pData in the following 
+ format: 
Where 
+ EASizeBufStruc { 
pArgDat pointer to union whose contents depend on {ArgType.|+ unsigned short easb MaxEASize /* Max. sizt 
Union is: + EA suppofi 
+ unsigned long easb MaxEAListSize /* Max. ful 
union argdat { + supported 
+ ) 
/* pArgType = 1, FileHandle directed case */ 
struct sf { 
struct sffsi far * psfsi; pParm address of application input parameter area. Addressing 
struct sffsd far * psfsd; of this data area has not been validated by the kerne! 
he (See FSH PROBEBUF). 
/* pArgType = 2, Pathname directed case */ + lenParm byte length of application input parameter area. 
struct cd { 
struct cdfsi far * pcdfsi; + plenParmIO On input, contains the length in bytes of the 
struct cdfsd far * pcdfsd; + parameters being passed to the FSD in pParm. On return, 
char far * pPath; + contains the length in bytes of data returned in pParm 
unsigned short iCurDirEnd; + by the FSD. The length of the data returned by the FSD 
¥ + in pParm must not exceed the length in lenParm. 
+ Addressing of this area have not been validated by the 
/* pArgType = 3, FSD Name directed case */ + kernel] (see FSH PROBEBUF). 
/* garbage */ 
}; pData address of application output data area. Addressing of 
this data area has not been validated by the kernel (See 
FSH_PROBEBUF) . 
iArgType indicator of argument type. 
+ lenData byte length of application output data area. 
* iArgType = 1 means that  pArgDat->sf.psfsi and 
pArgDat->sf.psfsd point to an sffsi and sffsd, {+t plenDataIO On input, contains the length in bytes of the data 
respectively. + being passed to the FSD in pData. On return, contains 
+ the length in bytes of data returned in pData by the 
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FSD. The length of the data returned by the FSD in 
pData must not exceed the length in lenData. Addressing 
of this area has not been validated by the kernel (see 
FSH PROBEBUF) . 


and the 
has not 


The 
locations 
been validated by the kernel. 


accessibility of the parameter and data buffers 
of the length of the data and parameter areas 
FS PROBEBUF must be used. 


func == 1] to return new error code 
2 to return the limits of the Extended 


All FSDs must support 
information, and func <= 
Attribute sizes. 


the error code is passed to the FSD in the first 
On return, the first word of the data 
the asciiz string containing an 

The data area contains the asciiz 
All FSDs are required to 


For func == l, 
word of the parameter area. 
area contains the length of 
explanation of the error code. 
string beginning at the second word. 
support func == 1. 
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Returns/Sets information for a filesystem device. 


int far pascal FS_FSINFO (flag, hVPB, pData, cbData, level) 





unsigned short flag; 
unsigned short hVPB; 
char far * pData; 
unsigned short cbData; 
unsigned short level; 
flag indicates retrieval (of information vs setting 
information. 
flag == 0 indicates retrieving information. 
flag == 1 indicates setting information on the 
media. 
All other values reserved. 
hVPB handle to volume of interest. 
pData address of application output data area. Addressing of 
this data area has not been validated by the kernel (See 
FSH_PROBEBUF) . 
cbData length of the application data area. For flag na 0, 
this is the length of the data the application wishes to 
retrieve. If there is not enough room for the entire 
level of data to be returned, the FSD will return 
ERROR_BUFFER_OVERFLOW. For flag == 1, this is the 
length of data to be sent to the file system. 
level information level to be returned. Level selects among a 
series of structures of data to be returned or set. See 
DOSQFSINFO and DOSSETFSINFO for information. 
None. 
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2.1.8.11.24 FS INIT - File system deceiver initialization: 


Purpose Request file system driver initialization. 
int far pascal FS INIT (szParcm, DevHelp, pMin{FSD) 
char fac * s2Patm; 
unsigned long De vHe ip; 
unsigned long far * pMinif'SD; 
Where 
s2Parm pointer to aserizg parameters tollowing the config.sys 
[FS= command that loaded the FSD. The FSD dues not need 
to verify this puinter. 

DevHelp address of the kernel entry point for the DevHelp 
routines. This is used exactly as the device driver 
Deviielp address, and can be used by an FSD that needs 
access to some of the device helper services. 

pMiniFSD pointer to data passed between the mini-FSD and the FSD 
or null. 

Remarks This call is made during system initialization to allow'the FSD to 

perform actions necessary for beginning operation. The FSD may 
successfully initialize by returning 0 or may reject installation 
(invalid parameters, incompatible hardware, etc) by returning the 
appropriate error code. If rejection is selected, all FSD 
selectors and segments are released. 
PMiniFSD will be null except when booting from a volume managed by 
an FSD and the exported name of the FSD matches the exported name 
of the maini-FSD. In tchiscase, pMiniFSD will point to data 
established by the mini-FSD (see mS_INIT). 
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2.1.8.11.25 FS_IOCTL - 1/0 Control) tor Devices: 


Purpose 


Where 


2.0 Funct ional Characteristics 


Perform control functions on the device specified by the opened 
device handle, 


int far pascal FS_IOCTI. (psffsi, ps€fsd, cat, func, 
pParm, lJenParm, 
pData, lenData) 

struct sffsi far * psffsi; 

struct sffsd far * psffsd; 


unsigned short cat; 

unsigned short func; 

chac far * pParm; 

unsigned short lenParm; 

chac far * pData; ‘ 
unsigned short lenData; 


psffsi pointer to file-system independent portion of open file 
instance. 

psffsd pointer to file-system dependent portion of open file 
instance. 

cal category of function to be performed. 

func function within category to be performed. 

pParm address of application input parameter area. Addressiny 


of this data area has not been validated by the kerne! 
(See FSH PROBEBUF). A null value indicates that the 
parameter is unpsecified for this function. 


lenParm byte length of application input parameter area. If 
lenParm is 0 and pParm is not null, it means the data 
buffer length is unknown due to the request beiny 
submitted via an old IOCTL or DOSDEVIOCTL interface. 


pData address of application output data area. Addressing of 
this data area has not been validated by the kernel (See 
FSH_PROBEBUF). A null value indicates that the 
parameter is unpsecified for this function. 

lenData byte length of application output data area. If lenData 

is O and pData is not null, it means the data buffer 

length is unknown due to the request being submitted via 

an old IOCTL or DOSDEVIOCTL interface. 
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2.1.8.11.26 FS_MKDIR ~- Make Subdirectory: 


Purpose Create the specified directory. 
int far pascal FS MKDIR (pedfsi, pcedfsd, 
pName, iCurDirEnd, 
pEABu f ) 

struct cdfsi far * pedfsi; 

struct cdfsd far * pcdfsd; 

char far * pName; 

unsigned short iCurDirEnd: 

char far * PEABu f ; 

Where 

pedfsi pointer to file-system independent working directory 
Structure. 

pedfsd pointer to file-system dependent working directory 
structure. 

pName pointer to asciiz name of directory to be created. The 
FSD does not need to verify this pointer. 

iCcurDirEnd index of the end of the current directory in pName. 
This is used to optimize FSD path processing. If 
icurDirEnd == -1 there is no current directory relevant 
to the name text, i.e. a device. 

pEABuf pointer to extended attribute buffer. This buffer 
contalns attributes that will be set upon creation of 
the new directory. If NULL, no extended attributes are 
to be set. Addressing of this data area has not been 
validated by the kernel (See FSH_PROBEBUF). 

Remarks The FSD needs to do the time stamping itself; there is no aid inf 
the kernal for time stamping sub-directories. FAT only supports 
creation time stamp and sets the other two fields to zeros. An FSD 
should do the same. The FSD can obtain the current time/date from 
the infoseg. 

A new directory called pName should be created if possible. The 
standard directory entries ‘°.’ and °..’ should be put into the 
directory. 
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2.1.8.11.27 FS_MOUNT - Mount/Unmount volumes: 


Purpose 


Where 


2.0 Functional Characteristics 


Examination of a volume by an FSD to see if it recognizes the file 
system format. 


int far pascal FS MOUNT (flag, pvpfsi, pypfsd, hVPB, pBoot) 
unsigned short flag; 

struct vpfsi far * pvpfsi; 

struct vpfsd far * pvpfsd; 

unsigned short hVPB; 

char far * pBoot; 


flag indicates operation requested. 


flag == 0 indicates that the FSD is 
Mount Or accept a volume. 


requested to 


flag == 1 indicates that the FSD is being advised 
that the specified volume has been removed. 


flag == 2 indicates that the FSD is requested to 
release all internal storage assigned to that volume 
as it has been removed from its drive and the last 
kernel-managed reference to that volume has been 
removed, 


flag == 3 indicates that the FSD is requested to 
accept the volume regardless of recognition in 
preparation for formatting for use with the FSD. 

The value passed to the 


All other values reserved. 


FSD will be valid. 


pointer to file-system-independent portion of VPB. If 
the media contains an OS/2-recognizable boot sector, 
then the vpi_vid field contains the 32-bit identifier 
for that volume. If the media does not contain such a 
boot sector, the FSD must generate a unique label for 
the media and place it into the vpi vid field. 


pvpfsi 


pointer to file~-system-dependent portion of VPB. The 
FSD may store information as necessary into this area. 


pvpfsd 


hVPB handle to volume. 


pointer to sector 0 
is ONLY valid when 


PBoot read from the media. This pointer 


flag == 0. The buffer the pointer 
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refers to MUST NOT BE MODIFIED. The pointer is always 
valid and does not need to be verified when flag == 0; 
if a read error occurred, the buffer will contain 
zeroes. 


The FSD should examine the volume presented and determine whether 
it recognizes the file system. If so, it should return zero after 
having filled in appropriate parts of vpfsi and vpfsd. The 
vpi_vid and vpi_ text fields must be filled in by the FSD. If the 
FSD has an OS/2 format boot sector, it must convert the label from 
the media into asciiz form. The vpi hDev field will be filled in 
by OS/2. If the volume is unrecognized, the driver should return 
non-zero. 


The vpi_text and vpi vid must be updated by the FSD each time 
these values change. 


The contents of the vpfsd are as follows: 


(FLAG = 0) 
The FSD is expected to issue an FSD FINDDUPHVPB to see 
if a duplicate VPB exists if one does exists the VPB 
fs dependent area of the new VPB is invalid and the 
new VPB will be unmounted after the FSD returns from 
the MOUNT. The FSD is expected to update the fs 
dependent area of the old duplicate VPB. 


If no duplicate VPB exists the FSD should initialize 
the fs dependent. 


(FLAG = 1) 
VPB fs dependent part is same as when FSD last 
modified it. 


(FLAG = 2) 
VPB fs dependent part is same as when FSD last 


modified it. 


After media recognition time, the volume parameters may be 
examined using the FSH_GETVOLPARM call. The volume parameters 
should not be changed after media recognition time. 


During a mount request, the FSD may examine other sectors on the 
media by using FSH DOVOLIO to _ perform the I/O. If an 
uncertain-media return is detected, the FSD is expected to clean 
up and return ERROR_UNCERTAIN MEDIA in order to allow the volume 
mount logic to restart on the newly-inserted media. The FSD must 
provide the buffer to use for additional 1/0. 


The kernel manages the VPB via a ref count. All volume-specific 
objects are labelled with the appropriate volume handle and 
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represent references to the VPB. When all kernel references to a 
volume disappear, FS_ MOUNT is called with flag == 2, indicating a 
dismount request. 


When the kernel detects that a volume has been removed from its 
drive, but there are still outstanding references to the volume, 
FS MOUNT is called with flag == 1 to allow the FSD to drop clean 
(or other regenerable) data for the volume. Data which is dirty 
and cannot be regenerated should be kept so that it may be written 
to the volume when it is remounted in the drive. 


When a volume is to be formatted for use with an FSD, the kernel 
calls the FSD’s FS MOUNT entry with flag == 3 to allow the FSD to 
prepare for the format operation. The FSD should accept the 
volume even if it is not a volume of the type that FSD recognizes, 
since the point of format is to change the filesystem on the 
volume. The operation may be failed if formatting doesn’t make 
any sense. (For example, an FSD which supports only CD-ROM.) 


Since the hardware does not allow for kernel-mediated removal of 
media, it is certain that the unmount request is issued when the 
volume is not present in any drive. 
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2.1.8.11.28 FS_MOVE - Move a File or Subdirectory: 


Purpose 


Where 


Remarks 


2.0 Functional Characteristics 


Moves (renames) the specified file or subdirectory. 


int far pascal FS_MOVE (pcdfsi, pcedfsd, 
pSrc, iSrcCurDirEnd, 
pDst, iDstCurDirEnd) 


struct cdfsi far * pcedfsi; 
struct cdfsd far * pcdfsd; 


char far * pSrc; 
unsigned short iSrcCurDirEnd; 
char far * pNst; 


unsigned short iDstCurDirEnd; 


pedfsi pointer to file-system independent working directory 
structure. 

pedfsd pointer to file-system dependent working directory 
structure. 

pSrce pointer to asciiz name of source file/directory. The 


FSD does not need to verify this pointer. 


iSrcCurDirEnd index of the end of the current directory in pSrc. 
This is used to optimize FSD path processing. If 
iSrcCurDirEnd =< -1 there is no current directory 
relevant to the source name text. 


pDst pointer to asciiz name of destination file/directory. 
The FSD does not need to verify this pointer. 


iDstCurDirEnd index of the end of the current directory in pDst. 
This is used to optimize FSD path processing. If 
{DstCurDirEnd == -1 there is no current directory 
relevant to the destination name text. 


The file specified in filename should be moved or renamed to be 
destfile if possible. 


Neither the source nor the destination filename may contain 
wildcard characters. 


In the case of a Subdirectory move, system does the following 
checking: 


" No files in this directory or its sub-directories are open. 
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* This directory or any of its sub-directories is not the 
current directory for any process in the system. 


In addition, system also checks for circularity in source and 
target directory names; i.e. the source directory is not a prefix 
of the target directory. 


Reminder: OS/2 does not validate input parameters, so FSD should 
call FSH_PROBEBUF where appropriate. 
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2.1.8.11.29 FS _NEWSIZE - Change File’s Logical Size: 


Purpose Changes a file’s logical (EOD) size. 
| int far pascal FS_NEWSIZE (psffsi, psffsd, len, I0flag) 
struct sffsi far * psffsi; 
struct sffsd far * psffsd; 
* unsigned long len; 
| unsigned short I0flag; 
Where 
psffsi pointer to file-system independent portion of open file 
instance. 
psffsd pointer to file~system dependent portion of open file 
instance. 
len desired new length of file. 
( IOflag indicates information about the operation on the handle. 
j 1IOflag == 0x0010 tndicates write-through. 
| IOflag == 0x0020 indicates no-cache. 
+ Remarks The FSD should return an error if an attempt is made to set the 
+ size to beyond the end of the direct access device. 
The file system driver should attempt to set the size (EOD) of the 
file to newsize and update sfi_size if successful. If the new size 
is larger than the currently allocated size, the file system 
driver should to the extent possible arrange for efficient access 
to the newly allocated storage. 
{ Of the information passed itn 10flag, the write-through bit isa 
| MANDATORY bit in that any data written to the block device must be 
{ put out on the medium before the device driver returns. The 
} no-cache bit, on the other hand, is an advisory bit that says 
t whether the data being transferred is worth caching or not. 
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} 2.1.8.11.30 FS _NMPIPE - Do a remote named pipe operation: 


| Purpose 


Where 


Perform a special purpose named pipe operation remotely. 


int far pascal FS _NMPIPE( psffsi, psffsd, OpType, pOpRec, 
pData, pName ); 

psffsi; 

psffsd; 

OpType; 

pOpRec; 

pData; 

pName; 


struct sffsi far * 
struct sffsd far * 
unsigned short 
union npoper far * 
char far * 

char far * 


psffsi pointer to file-system independent pcrtion of open file 


instance. 
psffsd 


pointer to file-system dependent portion of open file 


instance. 
operation to be performed. will take on 
the following values: 


OpType This parameter 


Ox21 
0x01 
0x22 
0x23 
0x24 
0x25 
0x26 
Oxi 
0x31 
0x53 
0x54 
0x58 


NMP_GetPHandState 
NMP_SetPHandState 
NMP PipeQInfo 

NMP PeekPipe 

NMP Connect Pipe 
NMP _DisconnectPipe 
NMP_TransactPipe 
NMP_READRAW 
NMP_WRITERAW 

NMP WAITPIPE 
NMP_CALLPIPE 
NMP_ONmPipeSemState 


pOpRec data record which varies depending on the value of 
OpType. The first parameter in each structure encodes 
the length of the parameter block. The second parameter 
if mon-zero indicates that the pData parameter is 
supplied and gives its length. The following record 


formats are used: 
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union npoper { 


struct phs_param phs; 
struct npi_param npi; 
struct npr_param npr; 
struct npw_param npw; 
struct npq param npq; 
struct npx_param Npx; 
struct npp param NPp; 
struct npt_param npt; 
struct qnps param qnps; 
struct npc_param npc; 
struct npd_ param npd; 


}: /* npoper */ 


/* Get/SetPHandState parameter block */ 


struct phs_param { 
short phs_len; 
short phs_dlen; 
short phs_pmode; /* pipe mode set or returned */ 


/* DosQNmPipeInfo parameter block, 
* data is info. buffer addr */ 


struct npi_param { 

short npi_ilen; 

short npi_dlen; 

short npi_level; /* information level desired */ 
}; 


/* DosRawReadNmPipe parameters, 
* data is buffer addr */ 


struct npr_param { 
short npr_len; 
short npr_dlen; 
short npr_nbyt; /* number of bytes read */ 


/* DosRawWriteNmPipe parameters, 
* data is buffer addr */ 


struct npw_param { 
short npw_len; 
short npw_dlen; 
short npw_nbyt; /* number of bytes written */ 
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/* NPipeWait parameters */ 


struct npq param { 
short npq_ len; 
short npq_dlen; 
long npq_timeo; /* timeout in milliseconds */ 
short npq_ prio; /* priority of caller */ 


/* DosCallNmPipe parameters, 
* data is in-buffer addr */ 


unsigned short 
unsigned short 
long 


npx_olen; /* 
npx_nbyt; /* 
mpx timeo; /* 


struct npx param { 
short npx_len; 
unsigned short npx_ilen; /* length of in-buffer */ 
char far *npx_ obuf; /* pointer to out-buffer */ 


length of out-buffer */ 
number of bytes read */ 
timeout in milliseconds */ 


/* PeekPipe parameters, data is buffer addr */ 

struct npp param { 
short npp_len; 
unsigned short npp dlen; 
unsigned short npp_nbyt; /* number of bytes read */ 
unsigned short npp_avi0; /* bytes left in pipe */ 
unsigned short npp avli; /* bytes left in current msg */ 
unsigned short npp_ state; /* pipe state */ 


/* DosTransactNmPipe parameters, 
* data is in-buffer addr */ 


struct npt_param { 
short npt_ len; 
unsigned short npt_ilen; /* length of in~buffer */ 
char far *npt_obuf; /* pointer to out-buffer */ 


unsigned short 
unsigned short 


npt_olen; /* length of out-buffer */ 
npt_nbyt; /* number of bytes read */ 
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/* QNmpipeSemState parameter block, 
* data is user data buffer */ 
struct qnps_ param { | 
unsigned short qnps_ len; /* length of parameter block */ 
unsigned short qnps dlen; /* length of supplied data block * 
long qnps_semh; /* system semaphore handle */ 
unsigned short qnps _nbyt; /* number of bytes returned */ 


/* ConnectPipe parameter block, no data block */ 

struct npc param { 
unsigned short npc _ len; /* Yength of parameter block */ 
unsigned short npc dlen; /* length of data block */ 


/* DisconnectPipe parameter block, no data block */ 

struct npd param { 
unsigned short npd_ len; /* length of parameter block */ 
unsigned short npd dlen; /* length of data block */ 

}; 


pData pointer to user data buffer for operations which require 
it. When the pointer is supplied, its length will be 
given by the second element of the pOpRec structure. 

pName pointer to remote pipe name. Supplied only for 


NMP_WAITPIPE and NMP_CALLPIPE operations. For these two 


operations only, the psffsi and psffsd parameters have 
no significance. 

Remarks This entry point is for support of special remote named pipe 
operations. Not all pointer parameters are used for all 
operations. In cases where a particular pointer has no 
significance, it will be NULL. 

This entry point will be called only for the UNC FSD. Non-UNC 
FSDs are required to have this entry point, but should return “not 
supported" if called. 

2.0 Functional Characteristics 267 


Microsoft Confidential 
OS/2 1.2 IFS Patent Documentation 


2.1.8.11.31 FS _OPENCREATE - Open a File: 


Purpose 


* Where 


2.0 Functional Characteristics 


Opens (or creates) the specified file. 


int far pascal FS_OPENCREATE (pcdfsi, pcdfsd, 
pName, iCurDirEnd, 
psffsi, psffsd, 
fhandflag, openfilag, 
pAction, attr, 


pEABu f) 
struct cdfsi far * pcdfsi; 
struct cdfsd far * pcdfsd; 
char far * pName; 
unsigned short iCurDirEnd; 
Struct sffsi far * psffsi; 
struct sffsd far * psffsd; 
unsigned short fhandflag; 
unsigned short openfilag; 


unsigned short far * pAction; 
unsigned short attr; 
char far * pEABu f ; 


pointer to file-system independent working directory 
structure. The contents of this structure are invalid 
for direct access opens. 


pedfsi 


pedfsd pointer to file-system dependent working directory 
structure. The contents of this structure are invalid 
for direct access opens. For remote character devices, 
this field will contain a pointer to a DWORD that was 
obtained from the remote FSD when the remote device was 
attached to this FSD. The FSD can use this DWORD to 
identify the remote device if it wishes. 

The FSD 


pName pointer to asciiz name of file to be 


does not need to verify this pointer. 


opened. 


iCurDirEnd index of the end of the current directory in pName. 
This is used to optimize FSD path processing. If 
iCurDirEnd == -1 there is no current directory relevant 
to the name text, i.e. a device. This value is invalid 
for direct access opens. 


psffsi pointer to file-system independent portion of open file 
instance. 
psffsd pointer to file~system dependent portion of open file 


instance. 
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openflag indicates the action taken when the file is present or 
absent. See the API documentation for the OpenFlag for 
DOSOPEN. The valve of openflag passed to the FSD will 
be valid. This value is invalid for direct access 
opens. 

pAction location where FSD returns a description of the action 
taken as governed by openflag. The FSD does not need to 
verify this pointer. The contents of Action are invalid 
on return for direct access opens. 

attr OS/2 file attributes. This value is invalid for direct 
access opens. 

pEABuf pointer to extended attribute buffer. This buffer 
contains attributes that will be set upon creation of a 
new file or upon replacement of an existing file. If 
NULL, no extended attributes are to be set. Addressing 
of this data area has not been validated by the kernel 
(See FSH _PROBEBUF). The contents of EABuf are invalid 
on return for direct access opens. 

Remarks For the file create operation, if successful, ST_SCREAT and 
ST PCREAT are set. This will cause the file to have 0 as last 
read and last write time. If it is desirable to make the last 
read/write time stamps same as the create time, simple set 
ST_SWRITE, ST _PWRITE, ST_SREAD, and ST_PREAD as well. 
For the file open operation, the FSD should copy all supported 
time stamps from the directory entry into the SFT. 
The sharing mode may be zero if this is a request to open a file 
from the 3.x box in compatibility mode or for an FCB request. 
FCB requests for read-write access to a_ read-only file should be] 
mapped to read~only access and reflected in the sfi_mode field by 
the FSD. An FCB request is indicated by the third bit set in the 
sfi type field. 
The flags defined for the sfi_ type field are: 
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fhandflag indicates the desired sharing mode and access mode for 
the file handle. See the API documentation for the 
OpenMode parameter for DOSOPEN. An additional access 
mode 3 is defined when the file is being opened on 
behalf of the OS/2 loaded for purposes of executing a 
file or loading a module. If the file system does not 
support an executable attribute, it should treat this 
access mode as open for reading. The value of fhandflag 
passed to the FSD will be valid. 
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type == 0x0000 indicates file. 

type == 0x0001 indicates device. 
type == 0x0002 indicates named pipe. 
type == 0x0004 indicates FCB open. 


All other values reserved. 


FSDs are required to initialize the sfi_type field, preserving the 
FCB bit. 


Also on entry, the sfi_hvpb field is filled in. If the file's 
logical size (EOD) is specified, it,will be passed in the sfi_ size 
field. To the extent possible, the file system should try to 
allocate this much storage for efficient access. 

Extended attributes are set for 1) the creation of a new file, 2) 
the truncation of an existing file, and 3) the replacement 
existing file. They are not set for a normal open. 


If the standard 0S/2 file creation attributes have been specified, 
they will be passed in the attr field. To the extent possible, 
the file system should interpret the extended attributes and apply 
them to the newly created or existing file. Extended attributes 
(EAs) that the file system does not itself use should be retained 
with the file and not discarded or rejected. 


FSDs are required to support direct access opens. These are 
indicated by a bit set in the sffsi.sfi_mode field. See’ DOSOPEN 
for information. Some of the parameters passed to the FSD for 
direct access opens are invalid, as described above. 


On a successful return, the following fields in the sffsi 
structure must be filled in by the file system driver: sfi_ size 
and all the time and date fields. 


The file-system dependent portion of open file instance passed to 
the FSD for FS_OPENCREATE will always be uninitialized. 


Infinite FCB opens of the same file by the same 3xbox process is 
supported. The first open is passed through to the FSD. 
Subsequent opens are not seen by the FSD. 


Any non-zero value returned by the FSD indicates that 
failed and the file is not open. 
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* 2.1.8.11.32 FS _PATHINFO - Query/Set a File’s Information: 


* Purpose Returns information for a specific path or file. 
* int far pascal FS PATHINFO (flag, pedfsi, pcedfsd, 
a pName, iCurDirEnd, 
level, pData, cbData) 
unsigned short flag; 
struct cdfsi far * pedfsi; 
struct cdfsd far * pcedfsd; 
char far * pName; 
unsigned short iCurDirEnd; 
unsigned short level; 
char far * pData; 
unsigned short cbData; 
Where 
+ flag is a bit defined as follows: 
+ flag == 0x0000 indicates retrieving information. 
+ flag == 0x0001 indicates setting information on the 
+ media. 
+ flag == 0x0010 indicates that the information being 
+ set must be written-throuhg onto the disk before 
+ returning. This bit is never set when retrieving 
+ information. 
All other values reserved. 
pedfsi pointer to file-system independent working directory 
structure. 
pedfsd pointer to file-system dependent working directory 
structure. 
pName pointer to asciiz name of file or directory for which 
* information is to be retrieved or set. The FSD does not 
* need to verify this pointer. 
* iCurDirEnd index of the end of the current directory in pName. 
el This is used to optimize FSD path processing. If 
bl iCurDirEnd == -1 there is no current directory relevant 
* to the name text, i.e. a device. 
level information level to be returned. Level selects among a 
series of structures of data to be returned or set. 
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address of application data area. Addressing of this 
data area has not been validated by the kernel (See 
FSH _PROBEBUF). When retrieval (flag == 0) is specified, 
the FSD will place the information into the buffer. 
When outputting information to a file (flag == 1), the 
FSD will retrieve that data from the application buffer. 


length of the application data area. For flag == 0, 
this is the length of the data the application wishes to 
retrieve. If there is not enough room for the entire 
level of data to be returned, the FSD will return 
ERROR_BUFFER OVERFLOW. For flag == 1, this is the 
length of data to be applied to the file. 


and DOSSETPATHINFO for 


4 


information level 


The FSD will not be called for DOSQPATHINFO level 5. 
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2.1.8.11.33 FS_PROCESSNAME - Allow FSD to modify name after 0S/2: 
canonicalization 


Purpose Allow FSD to modify filename to its own specification after the 
OS/2 canonicalization process has completed. 
int far pascal FS_PROCESSNAME (pNameHuf) 
char far * pNameBuf ; 
Where 
pNameBuf pointer to ASCII2 pathname. The FSD should modify the 
pathname in place. The buffer is guaranteed to be the 
length of che maximum path. The FSD does not need to 
verify this pointer. 
Remacks The resulting name must be within the maximum path length returned 
by DOSQSYSINFO. 
This routine allows the FSD to enforce a different naming 
convention than OS/2. For example, an FSD could remove blanks 
embedded in component names or return an error if it found such 
blanks. It ia called after the 0S/2 canonicalization process has 
succeeded. it is not called for FSH_CANONICALI2E. 
This routine will be called for ali APIs that use pathnames. 
This routine must return no erroc if the function ifs not 
supported. 
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2.1.8.11.34 FS_READ - Read from a File: 


Purpose ead the specified number of bytes from a file to a bulfer 
location. 

int far pascal FS_READ (psff{si, psf{sd, pData, pLen, I0flag) 

struct sffsi far * psffsi; 

Struct sffsd far * psffsd; 

char far * pData; 

unsigned short far * pLen; 

unsigned short 10flag; 

Where 

psffsi pointec to flle-system independent portion of open file 
instance. sfi posicion is the location within the file 
where the data its to be read from. The FSD should 
update the sfi position field. 

psf sd pointer to flle-system dependent portion of open file 
instance. 

pData address of application data area. Addressing of this 
data area has not been validated by the kernel {See 
FSH_PROBEBUF) . 

pLen pointer to length of the application data area. On 
input, this is the number of bytes that to be read. On 
output, this fs the number of byte successfully read. 
If the application data area is smaller than the length, 
no transfer is to take place. The FSD will not be 
called for zero length reads. The FSD does not need to 
verify this pointer. 

10flag indicates information about the operation on the handle. 

lOflag == 0x0010 indicates write-through. 
‘JOflag -= 0x0020 indicates no-cache. 

Remarks If read is successful and is a file, the FSD should = set 
ST_SREAD and ST PREAD to make the kernel time stamp last 
modification time in the SFT. 

Of the information passed in l0flaq, the write-through 
bit is a MANDATORY bit in that any data written to the 
block device must be put ovt on the medium before the 
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device driver returns. The no-cache bit, on the other 
hand, is an advisory bit that says whether the data 
being transferred is worth caching or not. 
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2.1.8.11.35 FS_RMDIR - Remove Subdirectory: 


Purpose 


Where 


Remarks 


2.0 Functional Characteristics 


Removes a subdirectory from the specified disk. 


int far pascal FS RMDIR (pedfsi, pcdfsd, 
pName, iCurDirEnd) 

struct cdfsi far * pcdfsi; 

struct cdfsd far * pcedfsd; 

char far * pName; 

unsigned short iCurDirEnd; 


pedfsi pointer to file-system independent working directory 
structure. ; 

pcedfsd pointer to file-system dependent working directory 
structure. 

pName pointer to asciiz name of directory to be removed. The 


FSD does not need to verify this pointer. 


iCurDirEnd index of the end of the current directory in pName. 
This is used to optimize FSD path processing. If 
iCurDirEnd == -1 there is no current directory relevant 
to the name text, i.e. a device. 


OS/2 has already assured that the directory being removed is not 
the current directory nor the parent of any current directory of 
any process. : 

other 


The FSD should not remove any directory that has entries 


than . and... in it. 
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* 2.1.8.11.36 FS_SETSWAP - Notification of swap-file ownership: 


Purpose 


Where 


* Note 


2.0 Functional Characteristics 


Perform whatever actions are necessary to support the swapper. 


int far pascal FS SETSWAP (psffsi, psffsd) 
struct sffsi far * psffsi; 
struct sffsd far * psffsd; 


psffsi pointer to file-system independent portion of open file 
instance of the swapper file. 
psffsd pointer to file-system dependent portion of open file 


instance. 
Swapping will not begin until this calls returns successfully. 
This call will be made during system initialization. 


The FSD will make all segments that are relevant to swap-file 1/0 
non-swappable (see FSH FORCENOSWAP). This includes any data and 


code segments accessed during a read or write. 
Any FSD that manages writeable media may be the swapper file 
system. 


FS SETSWAP may be called more than once for the same or different 
volumes or FSDs. FSDs should be prepared to see multiple swapping 
files on more than one volume in future releases of OS/2. 
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+ 2.1.8.11.37 FS_ SHUTDOWN - Shutdown File System for Power Off: 


+ Purpose 


> 


+ 


heer +t hehe HH HH + 


+> + 


+e ee er HHH + + + + 


+ + 


Remarks 


2.0 Functional Characteristics 


Used to shutdown an FSD in preparation for power-off or IPL. 


int far pascal FS SHUTDOWN (type, reserved) 
unsigned short type; 
unsigned long reserved; 


Where 


type indicates what type of a shutdown operation to perform. 

type == 0 indicates that the shutdown sequence is 
beginning. The kernel will not allow any new I0 
calls to reach the FSD. The only exception will be 
IO to the swap file by the swap thread through the 
FS READ and FS_WRITE entry points. The kernel] will 
still allow any thread to call  FS_COMMIT, 
FS_FLUSHBUF and FS SHUTDOWN. The FSD should 
complete all pending calls that might generate disk 
corruption. 


type == 1 indicates that the shutdown sequence is 
ending. An FS_COMMIT has been called on every SFT 
open on the FSD and following that an FS FLUSHBUF on 
all volumes has been called. All final clean up 
activity must be completed before this call returns. 


reserved reserved for future expansion. 
4 
From the perspective of an FSD, the shutdown sequence looks like 


this: 


First, the system will call the FSD’s FS SHUTDOWN entry with type 


== 0. This notifies the FSD that the system will begin committing 
SFTs in preparation for system power off. The kernel will not 
allow any new IO calls to the FSD once it recieves this first 
call, except from the swapper thread. The swapper thread will 


continue to call the FS READ and FS_WRITE entry points to read and 
write the swap file. The swapper thread will not attempt to grow 
or shrink the swap file nor should the FSD reallocate it. The 
kerne) will continue to allow FS COMMIT and FS _FLUSHBUF calls from 
any thread. This call should not return from the FSD until disk 
data modifying calls have completed to insure that a_ thread 
already inside the FSD does not wake and change disk data. 


will start 
see a commit for every SFT 


After the first FS_SHUTDOWN call returns, the kernel 
committing SFTs. The FSD will 
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associated with jit. During these FS_COMMIT calls, the FSD must} 2.1.8.11.38 FS WRITE - Write to a File: 
flush any data associated with these SFTs to disk. The FSD must 
not allow any FS COMMIT or FS FLUSHBUF call to block permanently. Purpose Write the specified mumber of bytes toa file from a _ buffer 


location. 
Once all of the SFTs associated with the FSD have been committed, 
FS FLUSHBUF will be called to flush all volumes. Following this, 
FS SHUTDOWN will be called with type == 1. This will tell the FSD int far pascal FS WRITE (psffsi, psffsd, 
to flush all buffers to disk. From this point, the FSD must not]! 7 pData, pLen, I0flag) 
buffer any data destined for disk. Reads and writes to the swap struct sffsi far * psffsi; 
file will continue, but the allocation of the swap file will not struct sffsd far * psffsd; 
change. Once this call has completed, no file system corruption char far * pData; 
should occur if power is shut off. unsigned short far * pLen; 
j unsigned short IO0flag; 
Where 
psffsi pointer to file-system independent portion of open file 
instance. sf{i position is the location within the file 
* where the data is to be written. The FSD should update 
. the sfi_position and sfi_size fields. 
psffsd pointer to file-system dependent portion of open file 
instance. 
pData address of application data area. Addressing of this 


data area has not been validated by the kernel (See 
FSH_PROBEBUF) . 


pLen pointer to length of the application data area. On 
input, this is the number of bytes that to be written. 
On output, this is the number of byte successfully 
written. If the application data area is smaller than 
| the length, no transfer is to take place. The FSD does 
{ not need to verify this pointer. 
1 10flag indicates information about the operation on the handle. 
| IOflag == 0x0010 indicates write-through. 


| I0flag == 0x0020 indicates no-cache. 


| Remark If write is successful and is a file, the FSD should set ST_SWRITE 


{ and ST PWRITE to make the kernel time stamp last modification time 

| in the SFT. 

+ The FSD should return an error for a direct access handle, if the 

+ write is beyond the end. 

1 Of the information passed in I0flag, the write-through bit is a 

{ MANDATORY bit in that any data written to the block device must be 
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put out on the medium before the device driver returns. The]* 


no-cache bit, on the other hand, is an advisory bit that says 
whether the data being transferred is worth caching or not. 


2.1.8.12 FS Helper Functions 


2.1.8.12.1 FS Services Supplied By OS/2: 


An FSD may access OS/2 services via two different paths: 


The set of DOS API calls available at initialization time 
those available to device drivers at initialization time. 


near front of spec.) This includes DosOpen, DosRead, DosWrite, 


and DosClose among others. 


2.1.8.12.2 FS Help Routines: 


FSDs are loaded as dynlink libraries and are able to 


via DOS API calls 
at initialization time, via dynlinks to OS/2 FS-help services at task time. 


4s equivalent to 
{See IPL section 
DosDevIoctl 


import 


services 


provided by the kernel. These services can be called directly by the file 


system, passing the relevant parameters. 


No validation of input parameters is done unless otherwise specified. 
FSD should call FSH_PROBEBUF where appropriate before calling the FS 


routine. 
When any service returns an error code, the FSD must 


from the helper to the FS router. 


wind out of 
particular FS call as soon as possible and return the specific error 


The/* 


help 


the 
code 


There are many deadlocks that may occur as a_ result of operations issued by 


FSDs. OS/2 provide no means whereby deadlocks between 
applications can be detected. 


The FSD helper routines are: 

FSH ADDSHARE Add a name to the sharing set 

FSH BUFSTATE Get or set buffer state 

FSH CANONICALIZE Convert pathname to canonical form 
FSH _CHECKEANAME Check extended attribute name validity 


FSH CRITERROR Signal a hard error to the daemon 
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FSH _DEVIOCTL Send IOCTL request to device driver 
FSH_DOVOLIO Volume-based sector-oriented transfer 

FSH _DOVOLIO2 Send volume-based IOCTL request to device driver 
FSH FINDCHAR Find first occurrence of char in string 
FSH_FINDDUPHVPB Locates equivalent hVPBs 

FSH _FLUSHBUF Flush buffered data to a volume 
FSH_FORCENOSWAP Force segments permanently into memory ) 
FSH GETBUF Buffered sector read 

FSH_GETFIRSTOVERLAPBUF Locates first buffer overlapping range 
FSH_GETVOLPARM Get VPB data from VPB handle 

FSH_INTERR Signal an internal error 

FSH_ISCURDIRPREFIX Test for a prefix of a current directory 
FSH_LOADCHAR Load character from a string 

FSH _PREVCHAR Move backward in string 

FSH_PROBEBUF User address validity check 

FSH_QSYSINFO Query system information 

FSH_RELEASEBUF Release the owned buffer 

FSH_REMOVESHARE Remove a name from the sharing set 
FSH_SEGALLOC Allocate a GDT or LDT segment 

FSH_SEGFREE Release a GDT or LDT segment 

FSH SEGREALLOC Change segment size 

FSH_SEMCLEAR Request a semaphore 

FSH_SEMREQUEST Request a semaphore 

FSH_SEMSET Set a semaphore 

FSH_SEMSETWAIT Set a semaphore and wait for clear 


FSH_SEMWAIT Wait for clear 
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+ FSH_STORECHAR Store character into string 
+ FSH UPPERCASE Uppercase asciiz string 
FSH _WILDMATCH Match using OS/2 wildcards 


FSH YIELD Yield CPU to higher priority threads 
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2.1.8.12.3 FSH_ADDSHARE - Add a name to the share set: 
FSH_ADDSHARE adds a name to the currently active sharing set. FSDs will use 
this call when executing deletes or renames with wildcard characters. 


FSH_ADDSHARE returns a share handle that must be used with a succeeding 
FSH_REMOVESHARE. 


int far pascal FSH ADDSHARE (pName, mode, hVPB, phShare) 


char far * pName; 
unsigned short mode; 
unsigned short hVPB; 


unsigned long far *phShare; 


Where 


4 


pName pointer to asciiz name to be added into the share set. 
The name must be in canonical form: no ‘*.’ or *..* 
components, uppercase, no metacharacters, and full 
pathname specified. 

mode sharing mode and access mode as defined in the DOSOPEN 
API. All other bits (Direct Open, Write-Through, etc) 
must be zero. 


hVPB handle to volume where the named object is presumed to 
exist. 


phShare pointer to location where a share handle is. stored. 
This handle may be passed to FSH _REMOVESHARE. 


Returns Error code if error detected, 0 otherwise. 


ERROR_SHARING VIOLATION - the file is open with a conflicting 
sharing/access mode. 


ERROR_TOO MANY OPEN FILES - there are too many files open at 
the present time. 


ERROR_SHARING BUFFER_EXCEEDED ~ there is not enough memory to 
hold sharing information. 


ERROR_INVALID_ PARAMETER - invalid bits in mode. 


ERROR_FILENAME_EXCED RANGE - pathname is too long. 


Note Do not call FSH_ADDSHARE for character devices. 


FSH_ADDSHARE may block. 
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To help avoid deadlocks, FSH _ADDSHARE should not be 
owning an OS/2 buffer. 


called while 


Reminder: OS/2 does not validate input parameters, so FSD should 


call FSH _PROBEBUF where appropriate. 
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2.1.8.12.4 FSH _BUFSTATE - Get or set buffer state: 
FSH_BUFSTATE is used retrieve or set the state of a buffer. 
int far pascal FSH _BUFSTATE (pBuf, flag, pState) 

char far * pBuf; 

unsigned short flag; 

unsigned short far * pState; 

Where 


pBuf pointer to buffer. This pointer was returned to the FSD 
by FSH_GETBUFFER 


flag indicates get or set buf state. 

flag == 0 indicates retrieve state | 

flag == 1 indicates set state i 

pState for set, points to new state of buffer on input. For 
retrieve, points to state of buffer. 


State =~ 0x0080 indicates dirty buffer. 


=. = owe eee = eee 


All other values are reserved. 


ee 


ZV Ob€ Sip Ogg 


Returns Error code if error detected, 0 otherwise. 
ERROR_INVALID PARAMETER - pointer to buffer is invalid or 
reserved state bits are set. 


Note To set the opposite of a defined state, call FSH _BUFSTATE with the 
bit not set. For example, to set a buffer not dirty, pass 0x00 as | 
the new state. 


Reminder: OS/2 does not validate input parameters, so FSD should 
call FSH _PROBEBUF where appropriate. 
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2.1.8.12.5 FSH_CANONICALIZE - Convert pathname to canonical form: 


FSH CANONICALIZE is used to convert a pathname to a canonical form by 
processing ’.’s and '..’s, uppercasing, and prepending the current directory 


to non-absolute paths. 


int far pascal] FSH _CANONICALIZE (pPathName, cbPathBuf, pPathBuf) 
char far * pPathName; 

unsigned short cbPathBuf; 

char far * pPathBuf; 


Where 


pPathName pointer to ascilz pathname to be canonicalized. 


cbPathBuf length of pathname buffer. 


pPathBuf pointer to buffer to copy canonicalized path into. 


Returns Error code if error detected, 0 otherwise. 


ERROR_PATH_NOT_ FOUND - invalid pathname - too many ’..'s. 


ERROR_BUFFER_OVERFLOW - pathname is too long. 


Note This routine process DBCS characters properly. 


The FSD is responsible for verifying the string pointers 


checking for segment boundaries. 


and 


FSH_CANONICALIZE should be called for names passed into the FSD 
raw data packets. For example, names passed to FS FSCTL in the 
parameter area should be passed to FSH_CANONICALIZE. This routine 
does not need to be called for explicit names passed to the FSD, 


i.e., the name passed to FS_OPENCREATE. 


Reminder: OS/2 does not validate input parameters, so FSD should 


call FSH_PROBEBUF where appropriate. 
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2.1.8.12.6 FSH CHECKEANAME - Check extended attribute name validity.: 


FSH_CHECKEANAME is used to check the extended attribute name for illegal 
characters, including wildcard characters, and correct length. 


int far pascal FSH_CHECKEANAME (iLevel, cbEAName, szEAName) 
unsigned short iLevel; 

unsigned long cbhEAName; 

char far * szEAName; 


Where 
iLevel extended attributes name checking level. 
iLevel == 0x0001 indicates OS/2 version 1.2 name 
checking. 
cbEAName length of extended attribute name, not including 
terminating NUL. 
SZEAName extended attribute name to check for validity. 
Returns Error code if error detected, 0 otherwise. 
ERROR_INVALID NAME - pathname contains invalid or wildcard 
characters or is too long. 
ERROR_INVALID PARAMETER - invalid level. 
Note This routine process DBCS characters properly. 
The set of invalid characters for EA names is the same as that for 
filenames. In v1.2, the maximum length of an EA name, not 
including terminating NUL, is 255 bytes. The minimum length is 1 
byte. 
The FSD is responsible for verifying the string pointers and 
checking for segment boundaries. 
FSH CHECKEANAME should be called for extended attribute names 
passed to the FSD. 
Reminder: OS/2 does not validate input parameters, so FSD should 
call FSH PROBEBUF where appropriate. 
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2.1.8.12.7 FSH CRITERROR - Signal a hard error to the daemon: + 


FSH _CRITERROR is used to pass an error from the current thread to the hard]+ 


error daemon, block waiting for a 


caller. Note If the user responds with an action that is not allowed, it is 
treated as FAIL. If FAIL is not allowed, it is treated as ASORT. 
ABORT is always allowed. 
int far pascal FSH _CRITERROR (cbMessage, pMessage, 
nSubs, pSubs, fAllowed) When ABORT is the final action, OS/2 does not return this as an 
unsigned short cbhMessage; indicator, only that FAIL was returned. The actual ABORT 
char far * pMessage; operation is generated when this thread of execution is about to 
unsigned short nSubs; return to user code, 
char far * pSubs; 
unsigned short fAllowed; The maximum length of the template'is 128 bytes (including the 
NUL). The maximum length of the message with text substitutions 
is 512 bytes. The maximum number of substitutions is 9. 
Where 
j If any action other than retry is selected for a given hard error 
cbMessage length of message template | popup, then any subsequent popups {within the same API call) will 
| be automatically failed; a popup will not be done. 
pMessage pointer to message template. This may contain 
replaceable paramters in the format used by the message] | This means that (except for retries) there can be at most one hard 
retriever. | error popup per call to the FSD. And, if the kernel generates a 
{ popup, then the FSD cannot create one. 
nSubs number of replaceable parameters. 
{ FSH CRITERROR will FAIL automatically if the user application has 
pSubs pointer to replacement text. The replacement text is af| set autofail, or if a previous hard error has occurred. 
packed set of ASCIIZ strings. 
FSH_CRITERROR may block. 
fAllowed bit mask of allowed actions: 
To help avoid deadlocks, FSH _CRITERROR should not be called while 
Bit 0x0001 on indicates FAIL allowed owning an OS/2 buffer. 
Bit 0x0002 on indicates ABORT allowed * Reminders OS/2 does not validate input parameters, so FSD should 
* call FSH _PROBEBUF where appropriate. 
Bit 0x0004 on indicates RETRY allowed 
Bit 0x0008 on indicates IGNORE allowed 
Bit 0x0010 on indicates ACKNOWLEDGE only allowed 
All other bits are reserved and must be zero. If 
bit 0x0010 is set, and any or some of bits 0x0001 to 
0x0008 are set, bit 0x0010 will be ignored. 
Returns Action to be taken: 
0x0000 ignore 
0x0001 retry 
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2.1.8.12.8 FSH_DEVIOCTL ~- Send IOCTL cequest to device driver: 


FSDs cail FSH DEVIOCTL to control device driver operation independent ly fron] | 


1/0 operat 


fons. 


This is typically in filtering DOSDEVIOCTL requests when 


passing the request on to the device driver. 


int far pa 


unsigned s 
unsigned } 
unsigned s 
unsigned 3s 


char far * 


unsigned short 


char far * 


unsigned short 


scal FSH DEVIOCTL {tlag, hDev, sfn, cat, func, 


hort. flag: 
ong hDev; 
hort sfn;: 
hort cat; 
unsigned short 


func; 


pPacm, cbParm, pData, cbData) 


pParm; 


cbParm; 


pData; 


cbData; 


Where 
flag indicates whether the FSD initiated the ca}) or not. 
1Oflag =» Ox0000 indicates that the FSD is just 
passing user pointers on to the helper. 
IOflag == 0x0001 indicates that the FSD initiated 
the Deviocr! call as opposed to passing a Deviocrl 
that it had received. 
All other bits are reserved and must be zero. 
hDev device handle obtained from VPB 
sfn system file number from open instance that caused the 
FSH_DEVIOCTL call. This field should be passed 
unchanged from the sfi selfisfn field. If no open 
inatance corresponds to this call, this field should be 
set to OxFFFF. 
cat category of IOCTL to perform 
func function within category of IOCTI. 
pParm long address to parametet alea 
cbParm length of parameter area 
pData long address to data area 
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cbData length of data area 


Remarks An FSD needs to be careful of pointers to buffers that 
are passed to it from FS_IOCTL, and what it passes to 
FSH DevIOCtl. It is possible that such pointers may be 
real mode pointers if the cal! was made from the 3x box. 
In any case, the FSD must indicate whether it initiated 
the DevIOCti call, in which case the kerne] can assume 
that the pointers are all protected mode pointers, or if 
it is passing user pointers on the the FSH _ Deviocr! 
call, in which case the mode of the pointers will depend 
on whether this is the 3x box or not. An important thing 
to note is that the FSD MUST NOT mix user pointers with 
its own pointers when using this helper. 


Returns Error code if error detected, 0 otherwise. 


ERROR INVALID FUNCTION - the function supplied is incompatible 
with the category supplied and the device handle supplied. 


ERROR INVALID_CATEGORY - the category supplied is incompatible 
with the function supplied and the device handle supplied. 


Device driver error code 


Note FSH_DEVIOCTL may block. 


To help avoid deadlocks, FSH_DEVIOCTL should not be called while 
owning an OS/2 buffer. 


Reminder: OS/2 does not validate input parameters, so FSD should 
call FSH _PROBEBUF where appropriate. 
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2.1.8.12.9 FSH _DOVOLIO - Volume-based sector-oriented transfer: 


FSH DOVOLIO performs I/O to the specified volume. It formats a device 
driver request packet for the requested I/0, locks the data transfer region, 
calls the device driver, and reports any errors to the hard error daemon 
before returning to the FSD. Any retries indicated by the hard error daemon 
or actions indicated by DOSERROR are done within the call] to FSH _DOVOLIO. 


int far pascal FSH_DOVOLIO (operation, fAllowed, hVPB, pData, pcSec, iSec) 


unsigned short operation; 
unsigned short fAllowed; 
unsigned short hVPB; 
char far * pData; 
unsigned short far * pcSec; 
unsigned long iSec; 
Where 
operation bit mask indicating read/read-bypass/write/ 
write-bypass/ verify-after-write/write-through and 
no-cache operation to be performed. 
Bit 0x0001 off indicates read. 
Bit 0x0001 on indicates write. 
Bit 0x0002 off indicates no bypass. 
Bit 0x0002 on indicates cache bypass. 
Bit 0x0004 off indicates no  verify-after-write| 
operation. 
Bit 0x0004 on indicates verify-after-write. 
Bit Ox0008 off indicates errors signalled to the 
hard error daemon. 
Bit 0x0008 on indicates hard errors will be returned 
directly. 
Bit 0x0010 off indicates I/O is not “write~-through". 
Bit 0x0010 on indicates I/O is "“write-through”. 
Bit 0x0020 off indicates data for this 1/0 should 
probably be cached. 
Bit 0x0020 on indicates data for this I/O should 
probably not be cached. 
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All other bits are reserved and must be zero. 
The difference between the “cache bypass" and the "no 
cache" bits is in the type of request packet that the 
device driver will see. With "cache bypass", it will 
get a packet with command code 24, 25, or 26. With "no 
cache", it will get the extended packets for command 
codes 4, 8, or 9. The advantage of the latter is that 
the write-through bit can also be sent to the device 
driver in the same packet, thus improving the 
functionality at the level of the device driver. 

fAllowed bit mask pf allowed actions: 

Bit 0x0001 on indicates FAIL allowed 

Bit: 0x0002 on indicateg ABORT allowed 

Bit 0x0004 on indicates RETRY allowed 

Bit 0x0008 on indicates IGNORE allowed 

Bit 0x0010 on indicates ACKNOWLEDGE only allowed 

All other bits are reserved and must be zero. If 

bit 0x0010 is set, none of the other bits may be 

set. 

hVPB volume handle for source of I/O 


pData long address of user transfer area 


sectors 'to be 
the number of 


pceSec pointer to number of 
transferred. On- return this is 
sectors successfully transferred. 


iSec sector number of first sector of transfer 


Returns Error code if operation failed, 0 otherwise. 


ERROR_PROTECTION VIOLATION - the supplied 


address/length is not valid. 

ERROR_UNCERTAIN MEDIA - the device driver can no 
longer reliably tell if the media has been changed. 
This occurs only within the context of an FS_MOUNT 
call. 

ERROR_INVALID PARAMETER - invalid bits in fAllowed. 


ERROR_TRANSFER_TOO_LONG ~ transfer is too long for 
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device 


Device-driver/device-manager errors listed "%------ 
SSS ie eee me Sai ees " on page ---. 


Note FSH DOVOLIO may be used at all times within the FSD. 
When called within the scope of a FS MOUNT call, it 
applies to the volume in the drive without regard to 
which volume it may be. However, since volume 


recognition is NOT complete until the FSD returns to the 


FS MOUNT call, the FSD must take care when an 
ERROR_UNCERTAIN MEDIA is returned. This indicates that 
the media has gone uncertain while we are trying to 


identify the media in the drive. 
the volume that the FSD was trying to recognize was 
removed. In this case, the FSD must release any 
resources attached to the hVPB passed in the FS_MOUNT 
call and return ERROR_UNCERTAIN_MEDIA to the FS MOUNT 
call. This will direct the volume tracking logic to 
restart the mount process. 


This may indicate that 


OS/2 will validate the user transfer area for 


access and size and will lock the segment. 


proper 


transfer and an OS/2 
released before signalling 


If an error occurs during the 
buffer is owned, it will be 
the hard error daemon. 


Verify-after-write or 
will be ignored. 


write-through specified on a read 


On 80386 processors, FSH DOVOLIO will take care of 
memory contiguity requirements of device drivers. It is 
advisable, hence, that FSDs use FSH _DOVOLIO instead of 
calling device drivers directly. This will improve 
performance of FSDs running on 80386 processors. 


FSH DOVOLIO may block. 


Reminder: OS/2 does not validate input parameters, s0 
FSD should call FSH _PROBEBUF where appropriate. 
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2.1.8.12.10 FSH _DOVOLIO2 - Send volume-based IOCTL request to device driver: 


FSDs call FSH _DOVOLIO2 to control device driver operation independently from 


I/O operations. This routine supports volume management for 10CTL 
operations. Any errors are reported to the hard error daemon before 
returning to the FSD. Any retries indicated by the hard error daemon or 


actions indicated by DOSERROR are done within the call to FSH_DOVOLIO2. 


int far pascal FSH DOVOLIO2 (hDev, sfn, cat, func, pParm, 
cbParm, pData, cbData) 

unsigned long hDev; 

unsigned short sfn; 

unsigned short cat; 

unsigned short func; 

char far * pParm; 

unsigned short cbParm; ' 

char far * pData; 

unsigned short cbData; 


Whe re 
hDev device handle obtained from VPB - 
sfn system file number from open instance that caused the 
FSH _DEVIOCTL call. This field should be passed 
unchanged from the sfi_selfsfn field. If no open 
instance corresponds to this call, this field should be 
set to OxFFFF. 
cat category of IOCTL to perform 
func function within category of IOCTL 
pParm long address to parameter area 
cbParm length of parameter area 
pData long address to data area 
cbData length of data area 
Returns Error code if error detected, 0 otherwise. 


ERROR_INVALID_ FUNCTION - the function supplied is incompatible 
with the category supplied and the device handle supplied. 


ERROR_INVALID CATEGORY - the category supplied is incompatible 
with the function supplied and the device handle supplied. 
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Device driver error code 


Note The purpose of this routine {ts to enable volume tracking with 


joctls. It is not available at the API level. 


FSH DOVOLIO2 may block. 


To help avoid deadlocks, FSH _DOVOLIO2 should not be called while 


owning an OS/2 buffer. 


System does normal volume checking for this request. 


Reminder: OS/2 does not validate input parameters, so FSD should 


call FSH _PROBEBUF where appropriate. 
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2.1.8.12.11 FSH_FINDCHAR - Find first occurrence of char in string:: 


Provides mechanism for find the first occurrence of any one of a set of 
characters in an ASCIIZ string taking into account DBCS considerations. 


int far pascal FSH FINDCHAR (nChars, pChars, ppStr) 
unsigned short nChars; 


char far * 


pChars; 


char far * far * ppStr; 


Where 
nChars number of chars in search list. 
pChars array of chars to search for. These cannot be DBCS 
characters. The NULL character cannot be searched for. 
ppStr pointer to character pointer to begin search from. This 
pointer is updated upon return to point to the character 
found. This must be an ASCIIZ string. 
Returns Error code if match failed, 0 otherwise. 
ERROR_CHAR_NOT FOUND - none of the characters were found. 
Note The search will continue’ until a matching character is found or 
the end of the string is found. 
The FSD is responsible for verifying the string pointers and 
checking for seqment boundaries. 
Reminder: 0OS/2 does not validate input parameters, so FSD should 
call FSH_PROBEBUF where appropriate. 
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2.1.8.12.12 FSH_FINDDUPHVPB - Locate equivalent hVPB: 


Provides mechanism for identifying previous instance of a volume during the 
FS MOUNT process. When OS/2 is recognizing a volume, it calls the FSD to 
mount the volume. At this point, the FSD may elect to allocate storage and 
buffer data for that volume. The mount process wil] allocate a new VPB 
whenever the media becomes uncertain (the device driver recognizes that it 
can no longer be certain that the media is unchanged). This VPB cannot be 
collapsed with a previously allocated VPB (due to a_ reinsertion of media) 
until the FS MOUNT cal] returns. However, the previous VPB may have’ some 
cached data that must be updated from the media (the media may have been 
written while it was removed). FSH_FPINODDUPHVPB allows the FSD to find this 
previous occurrence of the volume in order to update the cached information 
for the old VPB. Note that the newly created VPB will be unmounted if there 
{4s another, older VPB for that volume. 


int far pascal FSH FINDDUPHVPB (hVPB, phVPB) 
unsigned short hVPB; 
unsigned short far * phVPB; 


Where 
hVPB handle to the volume to be found 
PhvPB pointer to where handle of matching volume will be 
stored. 
Returns Error code if no matching VPB found. 0O otherwise. 
ERROR_NO_ ITEMS - there is no matching hVPB. 
Note Reminder: OS/2 does not validate input parameters, so FSD should 
call FSH PROBEBUF where appropriate. 
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~ Flush buffered data to a volume: 


takes dirty the buffer cache on a 


Optionally, the data can be discarded 


sectors contained in 


afterwards. 


int far pascal FSH FLUSHBUF 


(hVPB, fDiscard) 


unsigned short hVPB; 
unsigned short fDiscard; 


Where 


Returns 


| Note 


hVPB handle to the volume to be flushed 
fDiscard indicates disposition of cached data. 
fDiscard == 0 indicates don’t discard any buffers. 
fDiscard == 1 indicates discard clean buffers 
All other values are reserved. 
Error code if any write failed. 0 otherwise. 
ERROR_INVALID PARAMETER - the value of Operation is invalid. 
Device-driver/device-manager errors listed "------ ----- ----- 
-S-o=| sae “on page ---. 
If fDiscard = 1 and a write error occurred, the data in the 


buffer(s}) that generated the error is not discarded. 


See note under FSH GETBUF 
calls. 


for interactions with other buffer 


Reminder: 0OS/2 does not validate input parameters, so FSD 
cal] FSH_PROBEBUF where appropriate. 


should 


FSH _FLUSHBUF may block. 
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2.1.8.12.14 FSH _FORCENOSWAP - Force segments permanently into memory: 


An FSD may call FSH_FORCENOSWAP to force segments to be loaded into memory 
and marked non-swappable. All segments both in the load image of the FSD 
and those allocated via FSH_SEGALLOC are eligible to be marked. There is no 
way to undo the effect of FSH FORCENOSWAP. 

If an FSD is notified that it is managing the swapping media, it should make 
this call for the necessary segments. 


int far pascal FSH_FORCENOSWAP (sel) 
unsigned short sel; 


Where 
sel selector that is to be made non-swappable. 
Returns Error code if invalid selector. 
ERROR_INVALID_ ACCESS - the selector is invalid. 
ERROR_ACCESS DENIED - the selector is invalid or the selector 
belongs to another process. 
ERROR_DIRECT_ACCESS HANDLE - the handle doesn’t refer to a 
segment. 
ERROR NOT ENOUGH MEMORY - not enough physical memory to make 
segment non-swappable. 
ERROR SWAP_TABLE_FULL, ERROR_SWAP_FILE FULL, 
ERROR PMM_ INSUFFICIENT MEMORY - attempt to grow the swap file 
failed. 
Note FSH FORCENOSWAP may block. 
Reminder: OS/2 does not validate input parameters, so FSD should 
call FSH PROBEBUF where appropriate. 
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2.1.8.12.15 FSH_GETBUF - Buffered sector read: 

FSH_GETBUF is used to access the OS/2 sector cache to retrieve a sector from 
a particular volume. The pointer to the OS/2 buffer cache element is 
returned. The data in the buffer may be preread if desired. 


int far pascal FSH _GETBUF (iSec, fPreread, hVPB, ppBuf) 


unsigned long iSec; 
unsigned short fPreRead; 
unsigned short hVPB; 


char far * far * ppBuf?; 


Where 
iSec sector number on the volume to return 
fPreread indicates whether the sector should be preread. 

fPreread == 0x0000 indicates preread sector. 
fPreread == Qx0001 indicates no prereading of 
sector. 
All other values are reserved. 
hVPB handle to the volume 
ppBuf pointer to location where pointer to buffer data is 
returned 

Returns Error code if operation failed,:- 0 otherwise. 

ERROR_GETBUF_FAILED - the write to clear out a buffer failed 
or the read to fill the buffer in failed. 

Note FSH_GETFIRSTOVERLAPBUF, FSH _GETBUF and FSH _RELEASEBUF are used to 
obtain and release buffers. Any buffer that is owned by a thread 
is unavailable to all other threads until it is freed. At most one 
buffer may be owned by any thread. 

Freeing occurs by calling FSH_FLUSHBUF, FSH_RELEASEBUF, or 
FSH_GETBUF to retrieve another sector. 

The buffer returned is marked as being owned by the calling 
thread. If any OS/2 buffer is still owned by an FSD when the 
system call completes, the system will halt with an Internal 
Error, thus the FSD is responsible for ensuring that all system 
owned buffers are released before it returns to the router. 
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Not being preread is a performance optimization for when a file is 
being grown and a partial sector is being filled in. 


Reminder: OS/2 does not validate input parameters, so FSD should 
call FSH _PROBEBUF where appropriate. 


FSH GETBUF may block. 
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2.1.8.12.16 FSH GETFIRSTOVERLAPBUF ~ Locates buffer overlapping range: 


Provides mechanism for handling buffers that overlap a large transfer region 
within a file. When performing large transfers, the FSD needs to identify 
all buffers that contain data that overlap a particular region of the media. 
When writing to the media, these overlapping buffers must be filled in with 
the new data as they contain old data while when reading these buffers need 
to be copied over the data transferred from the media. 


Typically, when a large transfer is requested, the FSD will use an algorithm 
along the following lines: 


isecFirst = lowest sector number to be transferred 
isecLast = highest sector number to be transferred 


/* While there are sectors still to be transferred 
*/ 
while (isecFirst <= isecLast) { 


/* Find first buffer in cache that’s in the transfer 
* range. 
«/ 
FSH _GETFIRSTOVERLAPBUF {(hVPB, isecFirst, isecLast, stisecBuf, 
&pbuf) ; 


/* Perform the I/O to the first unbuffered part 
*} 
csec = ijsecBuf - isecFirst; 
if (csec != 0) 
FSH DOVOLIO (..., & csec, isecFirst); 


/* Handle the buffered data appropriately 
*/ 


/* Release the buffer 
e/ 


FSH _RELEASEBUF (); 


/* Reduce range of data-to-be-transferred 
*/ 
t{secFirst = isecBuf + 13 


/* Continue until no more sectors 


*/ 
) 
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int far pascal FSH_GETFIRSTOVERLAPBUF (hVPB, tsecFirst, isecLast, 
pisecBuf, ppBuf) 

unsigned short hVPB; 

unsigned long isecFirst; 

unsigned long isecLast; 

unsigned long far * pisecBuf; 

char far * far * ppBuf; 


data is 


Where 
hVPB handle for volume of I/O 
isecFirst logical sector number of beginning of range 
isecLast last logical sector number of range 
pisecBuf pointer to returned logical sector number of buffered 
sector 
ppBuf pointer to location where pointer to buffer 
returned 
Returns Error code if no overlapping buffer found. 0 otherwise. 
ERROR_NO_ ITEMS - no overlapping buffer was found. 
Note FSH_GETFIRSTOVERLAPBUF may block. 


Reminder: OS/2 does not validate input parameters, so FSD should 


call FSH _PROBEBUF where appropriate. 


See note under FSH GETBUF for interactions with other 


calls. 
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2.1.8.12.17 FSH_GETVOLPARM - Get VPB data from VPB handle: 


FSH_GETVOLPARM allows an FSD to retrieve file-system-independent and 
-dependent data from a VPB. Since the FS router passes in a VPB handle 
individual FSDs need to map the handle into pointers to the relevant 
portions. 


void far pascal FSH _GETVOLPARM (hVPB, ppVPBfsi, ppVPBfsd) 
unsigned short hVPB; 

struct vpfsi far * far * ppVPBfsi; 

struct vpfsd far * far * ppVPBfsd; 


Where 
hVPB volume handle of interest , 
PpVPBfsi location of where pointer to file-system- independent 
data is stored 
ppVPBfsd location of where pointer to file-system- dependent data 
is stored 
Returns Nothing i 
Note FSH _GETVOLPARM will not block. 
Reminder: OS/2 does not validate input parameters, so FSD should 
cal] FSH_PROBEBUF where appropriate. 
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2.1.8.12.18 FSH _INTERR - Signal an internal error: 


For reliability, if an FSD detects an interna! inconsistency during normal 
operation, the safest thing is for the FSD to shut down the = system as a 
whole, the reason being that it is not clear if the system as a whole is in 
a state that allows normal execution to continue. 


address of the caller 
The system then halts. 


When an FSD calls FSH_INTERR, the 
message is displayed on the console. 


and the supplied 


void far pascal FSH_INTERR (pMsg, cbMsg) 


char far * pMsg; 
unsigned short cbMsg; 


Where 
pMsg pointer to message text 
cbMsg length of message text 

Returns None, does not return. 

Note The code used to display the message is primitive. The message 
should contain ASCII characters in the range 0x20-Ox7E, optionally 
with 0x0D and Ox0A to break the text into multiple lines. 

The FSD must preface all such messages with the name of the file 
system. 

Maximum message length is 128 characters. Messages longer than 
this are truncated. 

Reminder: OS/2 does not validate input parameters, so FSD should 
call FSH PROBEBUF where appropriate. 
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2.1.8.12.19 FSH_ISCURDIRPREFIX - Test for a prefix of a current directory: 
Since the kernel manages ‘the text of each current directory for each 
process, the FSD must disallow any modification of any directory that is 
either a current directory of some process or the parent of any current 
directory of some process. _FSDs call FSH_ISCURDIRPREFIX to achieve this. 


FSH_ISCURDIRPREFIX will take the supplied path name, enumerate all current 


* directories in use and test to see if the specified path name is a prefix or 


» 


is equal to some current directory. 


int far pascal FSH_ISCURDIRPREFIX (pName) 
char far *pName; 


Where ’ 
pName pointer to path name. The name must be in canonical 
form: no *.’ or %.,..? components, uppercase, no 
metacharacters, and full pathname specified. 
Returns Error code if pName is the prefix of or equal to the current 
directory of a process, 0 otherwise. 
ERROR_CURRENT_ DIRECTORY - the specified path is a prefix of or 
is equal to the current directory of some process. 
Note If the current directory is the root and the pathname is “d:\", 
ERROR_CURRENT_ DIRECTORY will be returned. 
FSH_ISCURDIRPREFIX may block. 
Reminder: OS/2 does not validate input parameters, so FSD should 
call FSH PROBEBUF where appropriate. 
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2.1.8.12.20 FSH LOADCHAR - Load a character from a string: 


Provides mechanism for loading a character from a string taking into account 


DBCS considerations. 


void far pascal FSH _LOADCHAR (ppStr, pChar) 


chac far * far * 


ppStr; 


unsigned short far * pChar; 


Where 
ppStr pointer to character pointer to string. The character 
at this location will be retrieved and this pointer will 
be updated. 
pChar pointer to character returned. If character is| 
non-DBCS, the first byte will be the character and the 
second byte will be zero. 
Note Reminder: OS/2 does not validate input parameters, so 
FSD should call FSH _PROBEBUF where appropriate. 
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2.1.8.12.21 FSH_NAMEFROMSEN - Get the full path name from an SFN.: 


FSH_NAMEFROMSFN allows an FSD to retrieve the full path name 


for an object 


to which an SEN refers. | 


| 


void far pascal FSH_NAMEFROMSEN (sfn, pName, pcbName) 
unsigned short 


char far * 
unsigned short far * 


Where 


Returns 


Note 
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sfn 


pName 


pcbName 


Error code if the SFN is invalid, 


sfn; 
pName; 
pcbName 


system file number of file instance obtained from the 
sfi_selfsfn field of the file system independent part of 
the SFT for the object. 


location of where the returned full path name is to be 


stored. 


location of where the FSD places the size of the buffer 
pointed to by pName. On return, the kernel will fill 
this in with the length of the path name. The length 
does not include the terminating null character. The 
size of the buffer should be long enough to hold the 
full path name, or else an error will be returned. 


or the buffer is not big enough 


to hold the full path name. 0 if no error occurred. 


ERROR_INVALID HANDLE - the SFN is invalid. 


ERROR_BUFFER_OVERFLOW - the buffer is too short for the | 


returned path. 


FSH_NAMEFROMSFN will not block. 


Reminder: 


OS/2 does not validate input parameters, so FSD should 


call FSH _PROBEBUF where appropriate. 
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2.1.8.12.22 FSH _PREVCHAR - Decrement character pointer: 


Provides mechanism for decrementing a character pointer taking into account 
DBCS considerations. 


void far pascal FSH PREVCHAR (pBeg, ppStr) 
char far * pBeg; 
char far * far * ppStr; 


Where 


pBeg pointer to beginning of string 

pointer to character pointer. This value is decremented 
appropriately upon return. If it is at the beginning of 
the string, the pointer is not decremented. If it 
points to the second byte of a DBCS char, it will be 
decremented to point to the first byte of the char. 


ppStr 


Note The FSD is responsible for verifying the string pointer 


and checking for segment boundaries. 


Reminder: OS/2 does not validate input parameters, so 
FSD should call FSH PROBEBUF where appropriate. 
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2.1.8.12.23 FSH_PROBEBUF - User address validity check: 


arbitrary pointers to data, 
on these pointers before using them. 


Since users may pass in 
validity checks 


FSDs must perform 
Because OS/2 is 


multithreaded, the addressability data returned by FSH _PROBEBUF is only 
valid until the FSD blocks. Blocking, either explicitly or implicitly 
allows other threads to run, and possibly invalidate a user segment. 


Therefore, FSH _PROBEBUF must be reapplied after every block. 


FSH _PROBEBUF provides a convenient method for assuring that a user transfer 
address is valid and present in memory. Upon successful return, the user 
address may be treated as a far pointer and accessed up to the specified 
length without either blocking or faulting. This state of affairs is 
guaranteed up until the FSD returns or until the next block. 


Once FSH PROBEBUF detects a protection violation, the process will be killed 
as soon as possible. The OS/2 kernel will kill the process once it has 
exited from the FSD. 


On 80386 processors, FSH _PROBEBUF will insure that all touched pages are 
physically present in memory, so that the FSD will not suffer an implicit 
block due to a page fault. However, FSH _PROBEBUF does NOT guarantee that 
the pages will be physically contiguous in memory, since FSDs are not 
expected to do DMA. 


int far pascal FSH _PROBEBUF (operation, pData, cbData) 
unsigned short operation; 

char far * pData; 

unsigned short cbData; 


Where 
operation indicates whether read or write access is desired 
is to be 


operation == 0 indicates read 


checked. 


access 


operation == 1 indicates write access is to be 


checked. 


All other values are reserved. 


pData starting address of user data 
cbData length of user data 
If cbData is 0, a length of 64K is indicated. 
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if either the access to 
transfer region itself is 
0 otherwise. 


Error code 
the user 
inaccessible. 


partially 


ERROR_PROTECTION VIOLATION - access to 
region is illegal. 


FSH PROBEBUF may block. 


To help avoid deadlocks, FSH PROBEBUF should not be 
owning an OS/2 buffer. 


Reminder: OS/2 does not validate input parameters, 
call FSH _PROBEBUF where appropriate. 
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completely 


the indicated memory 


called while 


so FSD should 
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2.1.8.12.24 FSH _QSYSINFO - Query system information: 


FSH QSYSINFO queries 


the 


system about dynamic system variables and static 


system variables not returned by DOSQSYSINFO. 


int far pascal FSH_QSYSINFO (index, pData, cbData) 


unsigned short index; 
char far * pData; 
unsigned short cbData; 


Where 


index 


pData 


cbData 


Returns 


Note 


Reminder: 


variable to return 


index == 1 indicates maximum sector size 


index «= 2 indicates process identity. The data 
returned will be as follows: 
struct { 
unsigned short PID; 
unsigned short UID; 
unsigned short PDB 


2 


index == 3 
current thread. This will be returned in an unsigned 
short field. 


index == 4 indicates verify on write flag for the 
process. This will be returned in an unsigned char 
(byte) field. O means verify is off, non-O means it 
is on. : 


long address to data area 


length of data area 


Error code if error detected, 0 otherwise. 


ERROR_INVALID PARAMETER - invalid index. 
ERROR_BUFFER_OVERFLOW - the specified buffer is too 


short for the returned data. 


OS/2 does not validate input parameters, so 


FSD should call FSH_PROBEBUF where appropriate. 
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* 2.1.8.12.25 FSH _RELEASEBUF - Release the owned buffer: 


* FSH RELEASEBUF releases a buffer owned by the calling thread if any is 


* owned. 


void far pascal FSH_RELEASEBUF () 


Returns Nothing 

Note See note under FSH GETBUF for interactions with other buffer 
calls. 
FSH_RELEASEBUF will not block. 
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2.1.8.12.26 FSH_REMOVESHARE - Remove a share entry: 


FSH_REMOVESHARE is used to remove a previously-entered name from the sharing 
set. 


void far pascal FSH_REMOVESHARE (hShare) 
unsigned long hShare; 


Where 


hShare share handle returned by a prior call to FSH_ADDSHARE. 


Returns None 


Note Once a call to FSH_REMOVESHARE has peen issued, the share handle 
is no longer valid. 


FSH_REMOVESHARE may block. 


Reminder: OS/2 does not validate input parameters, so FSD should 
call FSH PROBEBUF where appropriate. 


To help avoid deadlocks, FSH REMOVESHARE should not’ be called 
while owning an OS/2 buffer. 
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2.1.8.12.27 FSH SEGALLOC - Allocate a GDT or LDT segment: 
An FSD may call FSH_SEGALLOC to allocate a GDT or LDT selector. The 


selector will have read/write access. 


int far pascal] FSH SEGALLOC (flags, cbSeg, pSel) 
unsigned short flags; 

unsigned long cbSeg; 

unsigned short far * pSel; 

Where 


flags indicates GDT/LDT, protection ring, 
swappable/non-swappable 


Bit 0x0001 off indicates GDT selector returned. 
Bit 0x0001 on indicates LDT selector returned. 
Bit 0x0002 off indicates non-swappable memory 
Bit 0x0002 on indicates swappable memory. 

Bits 13 and 14 are the desired ring number. 


All other bits are reserved and must be zero. 


cbSeg length of the segment 
pSel far address of location where allocated selector will be 
stored 


Returns Error code if allocation failed, 0 otherwise. 
ERROR_INTERRUPT - the current thread received a signal 


ERROR_INVALID_ PARAMETER - reserved bits in flags are set or 
requested size is too large 


ERROR_NOT_ ENOUGH MEMORY ~ too much memory is allocated 


Note 
It is strongly suggested that FSDs allocate all their data at 
ring 0 for maximal protection from user programs. 
GDT selectors are a scarce resource; the FSD must be prepared to 
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expect an error for allocation of a GDT segment. The FSD should 
limit itself to at most 10 total GDT segments. It is suggested 


that for each type of data, a large segment be allocated and 
divided into per-process records. 
FSH_SEGALLOC may block. 
Reminder: OS/2 does not validate input parameters, so FSD should 
call FSH PROBEBUF where appropriate. 
Care must be taken to avoid deadlocks between swappable segments 
and swapper requests. 
To help avoid deadlocks, FSH SEGALLOC should not be called while 
owning an OS/2 buffer. 
‘ 
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2.1.8.12.28 FSH_SEGFREE - Release a GDT or LDT segment: 
An FSD may call FSH_SEGFREE to release a segment previously allocated with 
FSH_SEGALLOC, or loaded as part of the FSD image. 


int far pascal FSH_SEGFREE (sel) 
unsigned short sel; 


Where 


sel selector to be freed 


Returns Error code if free failed, 0 otherwise. 


ERROR_INVALID_ACCESS - the selector is invalid 
Note FSH_SEGFREE may block. 


Reminder: 0OS/2 does not validate input parameters, so FSD should 
call FSH PROBEBUF where appropriate. 
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2.1.8.12.29 FSH_SEGREALLOC - Change segment size: 
An FSD may call FSH SEGREALLOC to change the size of a segment previously 
allocated with FSH _SEGALLOC, or loaded as part of the FSD image. The 


segment may be grown or shrunk. The segment may be moved in the process. 
When grown, the extra space is uninitialized. 


int far pascal FSH SEGREALLOC (sel, cbSeg) 
unsigned short sel; 

unsigned long cbSeg; 

Where 


se) selector of segment to be changed 


cbSeg new size to set for the segment . 


Returns Error code if free failed, 0 otherwise. 
ERROR_NOT_ENOUGH MEMORY - too much memory is allocated 


ERROR_INVALID_ACCESS - the selector is invalid 


Note FSH_SEGREALLOC may block. 


To help avoid deadlocks, FSH_SEGREALLOC should not be called while 
owning an OS/2 buffer. 


ov OPE Sib 0 d3 


Reminder: OS/2 does not validate input parameters, so FSD should 
call FSH PROBEBUF where appropriate. 
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2.1.8.12.30 FSH SEMCLEAR - Clear a semaphore: 


FSH SEMCLEAR allows an FSD to release a semaphore that was previously 
obtained via FSH_SEMREQUEST. 
int far pasca) FSH _SEMCLEAR (pSem) 
char far * pSem; 
Where 
pSem handle to system semaphore or long address of ram 
semaphore 
Returns Error code if free failed, 0 otherwise. 
ERROR_EXCL_SEM ALREADY OWNED - the exclusive semaphore is 
already owned. 
ERROR_PROTECTION_ VIOLATION - the semaphore is inaccessible. 
Note FSH _SEMCLEAR may block. 
To help avoid deadlocks, FSH_SEMCLEAR should not be called while 
owning an OS/2 buffer. 
Reminder: OS/2 does not validate input parameters, so FSD should 
cal] FSH PROBEBUF where appropriate. 
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* 2.1.8.12.31 FSH_SEMREQUEST - Request a semaphore: 


* FSH_SEMREQUEST allows an FSD to obtain exclusive access to a semaphore. 


*¢* + @& & 


int far pascal FSH SEMREQUEST (pSem, cmsTimeout) 


char far * 


pSem; | 


unsigned long cmsTimeout; 


Where 
pSem handle to system semaphore or long address of ram 
semaphore 
cmsTimeout number of milliseconds to wait 
Returns Error code if failed, 0 otherwise. 
ERROR_INTERRUPT - the current thread received a signal 
ERROR_SEM TIMEOUT - the timeout expired without gaining access 
to the semaphore. 
ERROR_SEM OWNER DIED - the owner of the semaphore died. 
ERROR TOO MANY SEM REQUESTS - there are too many semaphore 
requests in progress. 
ERROR PROTECTION_VIOLATION - the semaphore is inaccessible. 
Note The distinguished timeout value of OxFFFFFFFF indicates an 


infinite timeout. - 


The caller may receive access to the semaphore after the timeout 
period has expired without receiving an  ERROR_SEM TIMEOUT. 
Therefore, semaphore timeout values should not be used for exact 
timing and sequencing. 


FSH_SEMREQUEST may block. 


To help avoid deadlocks, FSH_SEMREQUEST should not be called while 
owning an OS/2 buffer. 


Reminder: OS/2 does not validate input parameters, so FSD should 
call FSH _PROBEBUF where appropriate. 
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2.1.8.12.32 FSH _SEMSET - Set a semaphore: 
FSH_SEMSET allows an FSD to set a semaphore unconditionally. 


int far pascal FSH_SEMSET (pSem) 
char far * pSem; 


Where 
pSem handle to system semaphore or long address of ram 
semaphore 
Returns Error code if invalid semaphore, 0 otherwise. 
ERROR EXCL SEM ALREADY OWNED - the exclusive semaphore is 
already owned. 
ERROR TOO MANY SEM REQUESTS - there are too many semaphore 
requests in progress. 
ERROR PROTECTION VIOLATION - the semaphore is inaccessible. 
Note FSH SEMSET may block. 
To help avoid deadlocks, FSH_SEMSET should not be called while 
owning an OS/2 buffer. 
Reminder: 0OS/2 does not validate input parameters, so FSD should 
call FSH PROBEBUF where appropriate. 
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2.1.8.12.33 FSH_SEMSETWAIT - Set a semaphore and wait for clear: 


FSH_SEMSETWAIT allows an FSD to wait for an event. 


The event is signalled 
by a call to FSH_SEMCLEAR. 


int far pascal FSH _SEMSETWAIT (pSem, cmsTimeout) 
char far * pSem; 
unsigned long cmsTimeout; 


Where 
pSem handle to system semaphore or long address of ram 
semaphore 
cmsTimeout number of milliseconds to wait 
Returns Error code if timeout occurred or invalid semaphore, 0 otherwise. 
ERROR _SEM TIMEOUT - the timeout expired without gaining access 
to the semaphore. 
ERROR_EXCL_ SEM ALREADY OWNED - the exclusive semaphore is 
already owned. 
ERROR_INTERRUPT - the current thread received a signal 
ERROR PROTECTION VIOLATION - the semaphore is inaccessible. 
* Note The caller may return after the timeout period has expired without 


receiving an ERROR_SEM TIMEOUT. fTherefore, semaphore timeout 
values should not be used for exact timing and sequencing. 


FSH _SEMSETWAIT may block. 


To help avoid deadlocks, FSH_SEMSETWAIT should not be called while 
owning an OS/2 buffer. 


Reminder: OS/2 does not validate input parameters, so FSD should 
call FSH PROBEBUF where appropriate. 
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2.1.8.12.34 FSH_SEMWAIT - Wait for clear: 


FSH_SEMWAIT allows an FSD 
call to FSH SEMCLEAR. 
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2.1.8.12.35 FSH _STORECHAR ~- Store a character in a string: 


to wait. for an event. The event is signalled by a]* Provides mechanism for storing a character into a string taking into account 
* DBCS considerations. | 


* void far pascal FSH_STORECHAR (chDBCS, ppStr) 


int far pascal FSH SEMWAIT (pSem, cmsTimeout) 


char far * pSem; 
unsigned long cmsTimeout; 


Where 
pSem handle to system semaphore or long address of ram 
semaphore 
cmsTimeout number of milliseconds to wait 
Returns Error code if free failed, 0 otherwise. 
t 
ERROR_SEM TIMEOUT - the timeout expired without gaining access|* 
to the semaphore. 
2 
ERROR_INTERRUPT - the current thread received a signal . 
ERROR_PROTECTION VIOLATION - the semaphore is inaccessible. 
Note The caller may return after the timeout period has expired without 
receiving an ERROR_SEM TIMEOUT. Therefore, semaphore timeout 
values should not be used for exact timing and sequencing. 
FSH SEMWAIT may block. 
To help avoid deadlocks, FSH_SEMWAIT should not be calied while 
owning an OS/2 buffer. 
Reminder: OS/2 does not validate input parameters, so FSD should 
call] FSH _PROBEBUF where appropriate. 
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unsigned short 


chDBCS; 


char far * far * ppStr; 


Where 


Note 
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chDBCS character to be stored. This may be either a single 
byte character or a double byte character with the first 
byte occupying the low-order position. 

ppStr pointer to character pointer where character will be 


stored. This pointer is updated upon return. 


The FSD is responsible for verifying the string pointer and 


checking for segment boundaries. 


Reminder: 0OS/2 does not validate input parameters, so FSD should 
call FSH_PROBEBUF where appropriate. 
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2.1.8.12.36 FSH _UPPEHCASE - Uppercase asciiz string: 


FSH_UPPERCASE is used to uppercase an asciiz string. 


int far pascal FSH UPPERCASE (szPathName, cbPathBuf, pPathBuf) 


char fac * szPathName; 
unsigned short cbPat hBuf; 
chac far *¢ pP at hBuf ; 
Where 
szPathName pointer to asciiz pathname to be uppercased. 
cbPathBuf length of pathname buffer. 
pPathBuf polnter to buffer to copy uppercased path into. 
Returns Excor code if error detected, O otherwise. 
ERROR BUFFER OVERFLOW - uppercased pathname is too long to fit 
in buffer. 
Note This routine processes DBCS characters properly. 
The FSD is responsible for verifying the string pointers and 
checking for segment boundaries. 
szPathName and pPathbul may point Lo the same place in memory. 
FSH UPPERCASE should be called for names passed into the FSD in 
raw data packets which are not passed to FSH CANONICALI2ZE and 
should be uppercased, |.e. extended attribute names. 
Reminder: OS/2 does not validate input parameters, so FSD should 
call FSH PROBEBUF where appropriate. 
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2.1.8.12.37 FSH _WILDMATCH ~- Match using 0S/2 wildcards: 


Provides mechanism for using OS/2 wildcards semantics to forma match 
between an input string and a pattern, taking into account oBCcS 
considerations. 


Wildcards provide a general mechanism for pattern matching file names. 
There are two distinguished characters that are relevant to this matching. 
The ‘2?’ character matches one character (not byte) except at a‘. of at the 
end of a string, where it matches zero characters. The '®? matches zero or 
moce characters (not bytes) with no implied boundaries except the end-of 
string. See discussion of meta characters. 


For example, “a*b" matches "ab" and "aCCCCCCCCCb”" while “a?b" matches “aCb* 
but does not match “aCCCCCCCCCb*. 


FSH_WIILOMATCH is case-sensitive. 
int far pascal FSH _WILOMATCH (pPat, pStr) 


char far “* pPat; 
chac far * pStr; 


Where 
pPat pointer to asciiz pattern string. Wildcards are present 
and are interpreted as described sbove. 
pStrc pointer to test string. 
Returna Error code if match failed, 0 otherwise. 
ERROR_NO META MATCH ~ the wildcard match failed. 
Note Reminder: OS/2 does not validate input parameters, so FSD should 
cali FSH PROBEBUF where appropriate. 
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2.1.8.12.38 FSH_YIELD - Yield CPU to higher priority threads: 


Provides mechanism for relinquishing the processor to higher-priority 
threads. FSDs run under the 2ms dispatch latency imposed on the 0OS/2 
kernel, meaning that no more than 2ms can be spent in an FSD without an 
explicit block or yield. FSH YIELD will test to see if another thread is 
runnable at the current thread’s priority or at a higher priority. If one 
exists, that thread will be given a chance to run. 


void far pascal FSH YIELD {) 


Returns None. 


2.1.8.13 Overview 


This package describes the changes to the boot architecture and extensions 
to the Installable Pile System (IFS) mechanism to enable booting from an 
File System Driver (FSD) managed volume (refered to as Bootable IFS. If the 
volume is on a remote system, it is refered to as Remote IPL.) 


This design centers around a new component refered to as the mini-FSD. The 
mini-FSD is similar to the FSD defined in the IFS spec. However, it has 
additional requirements placed on it for reading the base device drivers. 
These requirements are fully defined in the interfaces section. 


To satisfy its 1/0 requests, the mini-FSD may call the disk device driver 
imbedded in OS2KRNL (the bootable IFS case) or it may contain its own 
imbedded device driver (the remote IPL case). 


Along with the mini-FSD, a new utility refered to as the IFS SYS utility is 
required to initialize am FSD managed volume with whatever is required to 
satisfy the requirements of the mini-FSD and this spec. 


The IFS mechanism must be expanded slightly to include some additional calls 
which the mini-FSD may need while it is linked into the IFS chain. 
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2.1.8.14 Operational Description 


In order to establish a frame of reference, the present boot procedure |! 


(which uses the FAT file system) will be described first. 


2.1.8.15 FAT Boot Procedure 


The following figure represents the various major stages during the FAT boot 
procedure. 


[===s5- [seeeeeHe= [anaes Seee joaseson= Pseeeeres paSeraaeas > time 
POST IBMBOOT OS2LDR~ stagel stage2 stage3 
OS2KRNL~> 


Power applied to the machine, or pressing CTRL-ALT-DEL, causes control to 
get transfered to the power-on-self-test (POST) code. This code, among other 
things, initializes the interrupt vectors to get to the BIOS routines. It 
then scans the IO adapters looking for and linking in any code which exists 
on them. It then executes an interrupt 19h (INT 19) which causes control to 
be transfered to the reboot code. 


The BIOS’ interrupt 19h handler will read the boot sector from disk into 
memory at 7C00h and transfer control to it. 


The boot sector contains a data structure (BPB) which describes the disk’s 
parameters. It also contains code to read in the root directory, scan for 
OS2LDR, and read it into memory. The loader is very simple and requires that 
OS2LDR be located in contiguous sectors. It uses the BIOS’ interrupt 13h 
handler to do reads from the disk. Control is then transfered to OS2LDR 
along with a pointer to the BPB and the drive number required by interrupt 
13h. 


OS2LDR contains the OS/2 loader. It relocates itself to the top of low 
memory, then scans the root directory for OS2KRNL and reads it into memory. 
No restrictions are imposed on OS2KRNL. Again, it is loaded via BIOS's 
interrupt 13h handler. After the required fixups are applied, control is 
transfered to OS2KRNL along with a pointer to the BPB and the drive number. 


OS2KRNL contains the OS/2 kernel and initialization code. It switches to 
protected mode, relocates parts of itself to high memory, then scans the 
root directory for and reads in the base device drivers (stage 1). Once 
again, BIOS’s interrupt 13h is used to read the disk, but mode switching 
must be done. 
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OS2KRNL then switches to protection ring 3 and loads some of the required 
dynamic link libraries (stage 2) followed by the device drivers and file 
system drivers specified in CONFIG.SYS (stage 3). This is done with 
standard DOS calls and therefore goes thru the regular file system and 
device drivers. 


2.1.8.16 Non-FAT Boot Procedure 


The following figure represents the various major stages during the non-FAT 


boot procedure. 


“black 
box" 


POST OS2LDR stagel stage2 


OS2KRNL-> 


the boot architecture 
events from the time 


In order to enable both bootable IFS and remote IPL, 
is modified to assume nothing about the sequence of 


when POST executes the interrupt 19h to the time OS2LDR receives control 
(ie. the “black box" is running). However, it does assume that a memory 
image of the files OS2KRNL and the mini-FSD are in memory when OS2LDR is 


given control. The memory map must be as follows: 


pemecaseewnenes + Top of Low Memory 
{| reserved | 

$o----~------ + 

! OS2LDR | 

$aenen eee eae + paragraph boundary 
{1  OS2KRNL | 

$— mcnwoonmene + 10000h 

! mini-FSD | 

$oonn eee ~~ + 7C0h 

| reserved {| 

$e em enna e meena + 0 


The mini-FSD must be loaded in the range 7COh to OFFFFh. OS2KRNL must be 
loaded at 10000h. OS2LDR must be loaded on the next paragraph boundary 
above OS2KRNL. 


When OS2LDR receives control, it must also receive a pointer to the file 
images for OS2KRNL and the mini-FSD. If the mini-FSD intends to use 
MFSH DOVOLIO to do disk reads, it must also be passed the pointer to the BPB 
and the drive number. 
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OS2LDR will relocate the mini-FSD to high memory (above the 1-Meg boundary), 
then continue on with the same initialization before transfering control to 
OS2KRNL. 


When OS2KRNL receives control], it will go through the same initialization as 
before (stage 1) with a couple of exceptions. The module loader will be 
called to “load" the mini-FSD from its memory image stored by OS2LDR in high 
memory. Also, the mini-FSD will be called to read the base device drivers 
(one at a time) via the stage 1 interfaces. 


Before any of the dynamic link libraries are loaded, the mini-FSD will be 
linked into the IFS chain (actually, it will be the only link in the chain.) 
and asked to initialize via FS_INIT. The FS_INIT call marks the transition 
from stage 1 to stage 2. 


The dynamic link libraries are then loaded using the stage 2 
followed by the device drivers and file system drivers. 


interfaces, 


of the functions of 
replacement for the 


The mini-FSD is required to support only a small number 
an FSD. Therefore, the first FSD loaded must be the 
mini-FSD e 


After the replacement FSD has been loaded, it will be called at FS_INIT to 
initialize itself and take whatever action it needs to effect a smooth 
transition from the mini-FSD to the FSD. The FSD will then replace the 
mini-FSD in the IFS chain, as well as in any kernel data structures which 
keep a handle to the FSD (ie. SET, VPB). 


From this point on, the system continues normally. 


2.1.8.17 Interfaces 


The mini-FSD is built as a dynamic link library. 
exported by making the function names public. Helper functions are imported 
by declaring the helper names external:far. It is required only to support 
reading files and will be called only in protect mode. The mini-FSD may NOT 
make dynamic link system calls at init time. 


Supplied functions are 


Due to the special state of the system as it boots, 
for the mini-FSD during the stage 1 time frame is 
the model for stage 2. This 

between OS/2 and the mini-FSD. 


the programming model 
somewhat different than 
difference necessitates 2 different interfaces 


During stage 1, all calls to the mini-FSD will be to the MFS_ xxxx functions. 
Only the MFSH_xxxx helper functions are available. These are the interfaces 
which are addressed in this document. Many of these interfaces parallel the 
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interfaces defined in the IFS spec while others are unique to the mini-FSD. 


During stage 2, the mini-FSD is treated as a normal FSD. Calls will be to 
the FS_xxxx functions and all FSH_xxxx helper functions are available. 
Since these interfaces are covered in the IFS spec, they will not be 


repeated here. 


During stage 3, the mini-FSD is given a chance to release resources (via a 
call to MFS_TERM) and before being terminated. 


Transition from stage 1] to stage 2 is marked by calling the FS_INIT function 
in the mini-FSD. Transition from stage 2 to stage 3 is marked by calling 
FS INIT in the FSD. 


The following figure shows the functions called during a typical boot 
sequence: 
omen eee ree as= mini-FSD  ---rnm-eenn nnn FSD --- 
stage 1 stage 2 stage 3 | 
MFS INIT 
MFS OPEN \ 
MFS READ | repeated for each file 
MFS CHGFILEPTR | 
MFS CLOSE / 
FS INIT 
| FS MOUNT/ATTACH 
" FS OPEN \ 
! FS_ READ | repeated for each file 
; FS CHGFILEPTR / 
! FS _ INIT 
| MFS_ TERM 
v time FS READ 
Note that no files are open at the transition from stage 1 to _ stage 2. 


Also, only a single file at a time will be open during stage 1. 


Note that files and volumes will be open during the transition from stage 2 
to stage 3 (the mini-FSD to the FSD). The FSD must do whatever is necessary 
for it to “inherit® them. The FSD will NOT receive mounts/attaches or opens 
for volumes and files which were mounted/attached and opened by the 
mini-FSD. Also, multiple files may be open simultaniously during stages 2 
and 3. 

A special set of helper functions have been made available to the mini-FSD 
to support an imbedded device driver. This might be required for situations 
such as remote IPL where the boot volume is not readable via DOVOLIO. These 
special helper functions (refered to as imbedded device driver helpers) are 
available during all stages of the mini-FSD’s life. 


Since the mini-FSD is a new component being added to the boot sequence, a 
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new interface to OS2LDR is required. 


The mame and attributes of the minl-FSD must match EXACTLY the name and 
attributes of the replacement FSD. 


Calling conventions for all interfaces except OS2LDR are as specified in the 
IFS spec. 


2.1.8.18 Black Box to Mini-FSD Interface 


A data structure (it will be refered to as "BootData” from here on) may be 
passed from the black box to the mini-FSD hy including a pointer to it in 
the resource table (described in the OS2LDR interface below.) It must 


initially reside in the memory reserved for the mini-FSD’s use { 7C0h 
-OFFFFh). OS2LDR will relocate it to high memory in a segment all its own. 
A pointer to BootData will be available to the mini-FSD via the MFS_INIT 
interface. 


2.1.8.19 OS2LDR Interface 


When initially transfering control to OS2LDR, the following interface is 

defined: . 

DH boot mode flags (see below). 

BX logical sector number of first sector of cluster number 2 (ignored 
if DH[2} = 1). 

DL drive ID (0 for drive A, 80 for drive C) for boot volume (ignored 
if DH[G) = 1.) 

DS:SI pointer to the boot media’s BPB (ignored if DH[{0] = 1). 

ES:DI pointer to the resource table (if DH[2] = 1) or pointer to a copy 


of the root directory (if DH[2) = 0). 


The boot mode flags are defined as follows: 


bits 7-3 reserved; must be zero. 

bit 2 Flag to indicate the presence (1) or absence (0) of a mini-FSD. 

bit 1 Flag to indicate if the boot volume is local (0) or remote (1). 
This flag is used to inform OS/2 that a remote IPL is in progress. 
(Ignored if DH[2] = 0.) 

bit 0 Flag to indicate if the mini-FSD will use OS2LDR’s disk device 
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BPR is defined in the IFS spec and is refered to as 


The resource table is defined as follows: 


WORD number of entries in this table (3 of 4). 

WORD paragraph number where the OS2LOR file image was loaded. 
DWORD length of the OS2LDR file image (in bytes). 

WORD paragraph number where the OS2KRNL file image was loaded. 
DWORD length of the OS2KRNL file image {in bytes). 

WORD Paragraph number where the mini-FSD file image was loaded. 
DWORD length of the mini-FSD file image (in bytes). 

WORD paragraph number of BoutData. 

DWORD length of BootData (in bytes). 


2.1.8.20 Stage 1 Interfaces 


The 


following functions must be made available by the mini-FSD. These 


functions will be called only during stage }. 


MES CHGFILEPTR 
MES CLOSE 


MFS INIT 
MFS OPEN 
MFS READ 
Mrs TERM 


The following helper functions are available to the mini-FSD. 


functions may be called only durlng stage }. 


MFSH DOVOL10 
MFSH_INTERR 
MFSH SEGAL1OC 
MFSH SEGFREE 
MESH SEGREALLOC 
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(ignored if}| 2.1.8.20.1 MPS CHGFILEPTR: 


Purpose Move the file‘s logical read position pointer. 


Calling Sequence 
PUSH offset 
PUSH type 
CALL far pte MFS_CHGFILEPTR 


Where 


offset 
to form the new position within the file. 


type WORD tndicating the base of the seek operation. 


DWORD (signed) to be added to the current file position 


0 indicates seek relative to the beginning of the file. 


1 indicates seek relative to the current position within 


the file. 


2 indicates seek relative to the end of the file. 


Returns Error code if function failed, 0 otherwise. 


Remarks None. 


2.1.8.20.2 MPS CLOSE: 


Purpose Close the file. 


Calling Sequence 
CALL far ptc MEFS CLOSE 


Returns Error code if function failed, 0 otherwise. 


Remarks None. 


2.1.8.20.3 MES INIT: 


Purpose inform the mini-FSD that it should prepare itself for use. 
Calling Sequence 

PUSH® Boot Data 

PUSH® ReservedDrives 

PUSH@ VectorIPL 

PUSH@ BPA 

PUSHE pMiniFSD 
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PUSH@ DumpRout ine 
CALL far ptr MFS_INIT 


BootData Data passed from black box to mini-FSD (null if not 


passed). 


ReservedDrives BYTE which may be filled in by the mini~FSD with 
the number of drive letters (beginning with “"C") to skip 
over before assigning drive letters to local fixed disk 
drives (ignored if not remote IPL). The system will 
attach the reserved drives to the mini-FSD via a call to 
FS ATTACH just after the call to FS_INIT. 


DWORD which may be filled in by the mini-FSD with a 
pointer to a data structure which will be available to 
installable device drivers via the standard device 
helper function “GetDOSVar" (variable number 12). The 
first eight bytes of the structure MUST be a signature 
which would allow unique identification of the data by 
co-operating device drivers (ie. "IBMPCNET"). 


VectorIPL 


BPB BPB data structure (see OS2LDR interface). 


DWORD which is filled in by the mini-FSD with data to be 
passed on to the FSD. 


pMiniFSD 


DumpRoutine DWORD which is filled in by the mini-FSD with the 
address of an alternative stand-alone dump procedure. 


Error code if function failed, 0 otherwise. 


The mini-FSD should fill in the data pointed to by pMiniFSD with 
any 32-bit value it wishes to pass on to the FSD (see FS_INIT). 
OS/2 makes no assumptions about the type of data passed. 
Typically, this will be a pointer to important data structures 
within the mini-FSD which the FSD needs to know about. 
OS/2 will not free the segment containing BootData. It should be 
freed by the mini-FSD if appropriate. 


the mini-FSD which 
stand-alone dump 


The DumpProcedure is a_ routine provided by 
32-bit replaces the diskette based 0S/2 
procedure. This ptions routine is given control after the 
OS/2 kernel receives a stand-alone rtant dump request. The OS/2 
kernel places the machine in a_ stable, real] mode state in which 
most interrupt vectors contain their original power-up value. If 
this address is left at zero, the OS/2 kernel will attempt to 
initiate a storage dump to diskette, if a diskette drive exists. 
The provided routine must handle the dumping of storage to an 


acceptable media. 
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2.1.8.20.4 MEFS OPEN: 


Purpose 


Open the specified file. 


Calling Sequence 


Where 


Returns 


Remarks 


PUSH& Name 
PUSH® Size 
CALL far ptr MFS OPEN 


Name ASCIIZ name of the file to be opened. 
path but will not include a drive. 


It may include a 

Size DWORD which is filled in ,by the mini-FSD with the size 
of the file in bytes. 

Error code if function failed, 0 otherwise. 


Only one file at a time will be open via this interface. The 


drive will always be the boot drive. 


The current file position is set to the beginning of the file. 


2.1.8.20.5 MFS READ: 


Purpose 


Read the specified number of bytes from the file to a data area. 


Calling Sequence 


Where 

Data data area. The data area is guaranteed to be below the | 
1-Meg boundary. 

Length WORD which specifies the number of bytes to be read. On 
return, it has been filled in by the mini-FSD with the 
number of bytes successsfully read. 

Returns Error code if function failed, 0 otherwise. 
Remarks 

The current file position is advanced by the number of bytes 

read. 
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2.1.8.20.6 MFSH_ DOVOLIO: 
Purpose Read the specified sectors from the boot volume into a data area. 


Calling Sequence 
PUSH@ Data 
PUSHE cSec 
PUSH iSec 
CALL far ptr MFSH_DOVOLIO 


Where 
| 
Data data area. The data area must be below the 1-Meg 
boundary. 
| 
cSec WORD which specifies the number of sectors to be read. 


On return, it has been filled in by the helper with the 
number of sectors successsfully read. 


iSec DWORD which is the sector number of the first sector. I 
Returns Error code if function failed, 0 otherwise. 


ERROR _PROTECTION VIOLATION - the supplied address or length is}j 
invalid. 


Remarks The only media which can be read via this interface is the boot 
volume. The machine's interrupt 13h BIOS function is used to 
actually do the disk reads. The data area wil! be locked and 
unlocked by this helper. Soft errors are retried automatically. 
Hard errors are reported to the user via a message and the system 
is stopped. 


2.1.8.20.7 MFSH_INTERR: 
f 
Purpose Display a message on the screen and stops the system. This] 
function should be used when an inconsistency is detected with~-in}| 

the mini-FSD. 


Calling Sequence 


PUSHE® Msg 
PUSH cbMsg 
CALL far ptr MFSH_INTERR 
Where 
Msg message text. 
( 
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cbMsg WORD which is the length of the message text. 
Returns Does not return. 


Remarks See the notes under FSH_INTERR in the IFS spec. 


2.1.8.20.8 MFSH SEGALLOC: 
Purpose Allocate a seqment of memory. 


Calling Sequence 


PUSH Flag 

PUSH cbSeg 

PUSH@ Sel 

CALL far ptr MFSH_SEGALLOC ; 

Where 

Flag WORD which is one (1) if the memory must be below the 
l-Meg boundary or zero (0) if it’s location doesn’t 
matter. 

cbSeg 


DWORD which is the length of the segment. 
Sel WORD which is filled in by the helper with the selector. 
Returns Error code if function failed, 0 otherwise. 
ERROR _ NOT ENOUGH MEMORY - too much memory is already allocated. 
ERROR_PROTECTION VIOLATION - the supplied address is inuaiia: 


Remarks The memory allocated will have the following attributes: GDT, 
ring 0, non-swappable. 


Memory not allocated specifically below the 1-Meg boundary may be 
“given” to the FSD by passing the selector(s) via pMiniFSD (see 
MFS_ INIT and FS_INIT). 


2.1.8.20.9 MFSH_SEGFREE: 


Purpose Release a segment previously allocated with MFSH_ SEGALLOC, or 
loaded as part of the mini-FSD image. 


Calling Sequence 
PUSH Sel 
CALL far ptr MFSH_SEGFREE 
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Where 

Sel WORD which is the selector to be freed. 
Returns Error code if function failed, 0 otherwise. 

ERROR_PROTECTION VIOLATION - the supplied selector 1s invalid. 
Remarks None 


2.1.8.20.10 MFSH_SEGREALLOC: 


Purpose Change the size of a segment previously allocated with 
MFSH_SEGALLOC, or loaded as part of the mini-FSD image. 
PUSH Sel 
PUSH cbSeg 
CALL far ptr MFSH SEGREALLOC 
Where 
Sel WORD which is the selector. 
cbSeg DWORD which is the length of the segment. 
Returns Error code if function failed, 0 otherwise. 
ERROR_NOT_ENOUGH_MEMORY - too much memory {is already allocated. 
ERROR PROTECTION VIOLATION - the supplied selector is invalid. 
Remarks The segment may be grown or shrunk. When grown, the extra space is 


uninitialized. The segment may be moved in the process. 


2.1.8.21 Stage 2 Interfaces 


The intent of stage 2 is to use the mini-FSD as an FSD. Therefore, all the 
guildlines and interfaces specified in the IFS spec apply with the following 
exceptions. 


The following IFS functions must be fully supported by the mini-FSD: 
* FS ATTACH (remote mini-FSD only) 


* FS ATTRIBUTE 
* FS CHGFILEPTR 


2.0 Functional Characteristics 361 


Microsoft Confidential ‘ 
OS/2 1.2 IFS Patent Documentation 


FS CLOSE 
FS COMMIT 

FS_ INIT 

FS 10CTL 

FS_ MOUNT (local mini-FSD only) 

FS NAME 

FS OPENCREATE (existing file only) 
FS_PROCESSNAME 

FS READ 


>>? © +e ee eH 


Note that since the mini-FSD is only required to support reading, 
FS OPENCREATE need only support opening an existing file (not the create or 
replace options). 


None of the other functions required by the IFS spec are required of the 
mini-FSD but must be defined and should return the 
ERROR_UNSUPPORTED FUNCTION return code. 


functions specified in the IFS spec is 
the mini-FSD may NOT use any other 


The full complement of helper 
available to the mini-FSD. However, 
dynamic link calls. 


2.1.8.22 Stage 3 Interfaces 


The intent of stage 3 is to throw away the mini-FSD and use only the FSD. 
The following IFS functions must be supported by the mini-FSD: 


* FS TERM 


2.1.8.22.1 MFS_TERM: 


Purpose Inform the mini-FSD that it should prepare itself for termination. 
Calling Sequence 
CALL far ptr MFS_ TERM 


, 


Returns Error code if function failed, 0 otherwise. 

Remarks The system will NOT free any memory explicitly allocated by the 
mini-FSD via MFSH_SEGALLOC or FSH_SEGALLOC; it must be explicitly 
freed by the mini-FSD. (Memory allocated by the mini-FSD and 
"given" to the FSD need not be freed.) The system will free all of 
the segments loaded as part of the mini-FSD image immediately 
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after this call. 


2.1.8.23 Imbedded Device Driver Helpers 


The following helper functions are available to the mini-~FSD and may be 
called during stage 1, 2 or 3. These helpers are counterparts for some of 
the device help functions and are intended for use by a device driver 
imbedded within the mini-FSD. 


MFSH_CALLRM 

MFSH_ LOCK 
MFSH_PHYSTOVIRT 
MFSH_ UNLOCK 

MFSH UNPHYSTOVIRT 
MFSH_ VIRTTOPHYS 


*# #8 6 8 8 


2.1.8.23.1 MFSH_CALLRM: 


Put the machine into real mode, call the specified routine, put 
the machine back into protect mode and return. 


Purpose 


Calling Sequence 
PUSH@ Proc 
CALL far ptr MFSH_CALLRM 


Where 
Proc DWORD which is the PHYSICAL address of the routine to 
call. 
Returns Undefined. 
Remarks Only registers DS and SI will be preserved between the caller and 


the target routine. The selectors in the segment registers will 
be converted to segments before calling the target’ routine. 
Arguments may not be passed on the stack since a stack switch may 
occur. 


This helper allows the mini-FSD to access the ROM BIOS’ functions 
which typically run in real mode only. Great care must be taken 
in using this function since selectors used through-out the system 
are meaningless in real mode. While in real mode, no calls to any 
helpers may be made. 
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2.1.8.23.2 MFSH_ LOCK: 


Purpose Lock a segment in place in physical memory. 
Calling Sequence 

PUSH Sel 

PUSH@ Handle 

CALL far ptr MFSH_ LOCK 


Where 
Sel WORD which is the selector to be locked. 
Handle DWORD which is filled in by the helper with the lock 
handle. ' 
Returns Error code if function failed, 0 otherwise. 
ERROR PROTECTION VIOLATION - the supplied address or selector is 
invalid. 
Remarks This helper is analogous to the device driver LOCK helper with the 


following attributes: short term, biock until locked. 
2.1.8.23.3 MESH _PHYSTOVIRT: 
Allocate a selector and bind a physical address and length to it. 


Purpose 


Calling Sequence 


PUSH Addr 

PUSH Len 

PUSH® Sel 

CALL far ptr MFSH_PHYSTOVIRT 
Where 

Addr DWORD which is the physical address. 

Len WORD which is the length of the segment. 

Se] WORD which is filled in by the helper with the selector. 
Returns Error code if function failed, 0 otherwise. 


ERROR_NOT ENOUGH MEMORY - too many selectors already allocated. 
ERROR PROTECTION VIOLATION - the supplied address is invalid. 
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This helper is somewhat 
helper. A call to PHYSTOVIRT must 
UNPHYSTOVIRT to release the selector. 


be paired with 


2.1.8.23.4 MESH UNLOCK: 


Purpose 


Unlock a segment which was previously locked. 


Calling Sequence 


Where 


Returns 


Remarks 


PUSH Handle 
CALL far ptr MFSH_UNLOCK © 


Handle 
Error code if function failed, 0 otherwise. 
ERROR PROTECTION VIOLATION - the supplied address is invalid. 


This helper is analogous to the device driver UNLOCK helper. 


2.1.8.23.5 MPSH_UNPHYSTOVIRT: 


Purpose 


Release the selector allocated by MFSH PHYSTOVIRT. 


Calling Sequence 


Where 


Returns 


Remarks 


PUSH Sel 
CALL far ptr MFPSH_UNPHYSTOVIRT 


Sel WORD which is the selector. 


Error code if function failed, 0 otherwise. 
ERROR PROTECTION VIOLATION - the supplied selector is invalid. 


This helper is somewhat analogous to the device 


UNPHYSTOVIRT helper. A _ call to 
call to UNPHYSTOVIRT to release the selector. 
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2.1.8.23.6 MFSH VIRT2PHYS: 


Purpose Translate a virtual address to a physical address. 
Calling Sequence 

PUSH VirtAddr 

PUSH® PhysAddr 

CALL far ptr MFSH_VIRT2PHYS 


Where 
VirtAddr DWORD which is the virtual address to be translated. 
PhysAddr DWORD which is filled in by the helper with the physical 
address equivalent of the virtual address. 
Returns Error code if function failed, 0 otherwise. 
ERROR_PROTECTION VIOLATION - the supplied address is invalid. 
Remarks This helper is analogous to the device driver VIRTTOPHYS helper. 


2.1.8.24 Special Considerations 


2.1.8.25 Constraints 


fit between 7COh and OFFFFh, the size 
Further, the 


Since the mini-FSD’s file image must 
of the mini-FSD file image may not exceed approximately 62k. 


memory requirements of the mini-FSD may not exceed 64k. This is an 
arbitrary constraint, but is required to ensure bootability under various 
conditions. 
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2.1.8.26 Limitations 


The mini~FSD is only required to support reading of a file. Therefore, any 
call to DosWrite (or other non-supported functions) which becomes redirected 
to the mini-FSD may be rejected. For this reason, it is required that the 
IFS= statement which loads the FSD which will replace the mini-FSD be the 
first IFS= statement in CONFIG.SYS. Further, only DEVICE= statements which 
load device drivers required by that FSD should appear before the first IFS= 
statement. 


If the mini-FSD needs to switch to real mode, it must use the MFSH_CALLRM 
function. This is required to keep OS/2 informed of the mode switching. 


This design assumes that OS2KRNL will not grow without bounds. This design 
will work as long as the size of the OS2LDR, OS2KRNL pair remains below 
approximately 448k (assuming only 512k of low memory available in the 
machine. This is required by our objectives statement today, but may change 
in the future. If the objectives are changed to require 640k of low memory, 
this boundary moves up to around 576k.) This is also the reason OS2LDR must 
be located on the next paragraph boundary above OS2KRNL. 


2.1.8.27 Dependencies 


Each FSD which is bootable is required to provide their own "black box" to 
load OS2LDR, OS2KRNL and the mini-FSD into memory before OS2LDR is given 
control. 


Additionally, these FSDs are required to provide a_ fourth function in their 
utility dynamic link library (see the IFS spec) to support the OS/2 SYSINSTX 
utility. This function must do whatever is required to make the partition 
bootable. At the very least, it must tnstall a boot sector. It will 
probably also need to install the "black box", mini-FSD, OS2LDR and OS2KRNL. 
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/*static char *SCCSID = "@(#)fsd.h 


APPENDIX Ii 


1.31 89/08/03 *;*/ 


/* fsd.h_ - File system driver entry point declarations */ 


/* FS_ATTRIBUTE bit field values */ 


#define FSA_REMOTE 0x00000001 /* Set if REMOTE FSD */ 
#define FSA_UNC 0x00000002 /* Set if FSD implements UNC support */ 
#define FSA_LLOCK 0x00000004 /* Set if FSD needs lock notification* / 
#define CODWORKAREASIZE 8 

#define SFDWORKAREASIZE 30 

#define VPDWORKAREASIZE 36 


/* Volume Parameter structures */ 
#define VPBTEXTLEN 12 


struct vpfsi { 
unsigned long vpi_vid; 
unsigned long vpi_hDEV; 
unsigned short vpi_bsize; 
unsigned long vpi_totsec; 
unsigned short vpi_trksec; 
unsigned short vpi_nhead; 


/* 32 bit volume ID */ 

/* handie to device driver */ 
/* sector size in bytes */ 

/* total number of sectors */ 
/* sectors / track */ 

/* number of heads */ 


char vpi_text(VPBTEXTLEN]; /* volume name */ 


}; /* vptsi */ 


* 


* Predefined volume IDs: [note - keep this list in sync with list in 


* dos/dosinc/vpb.inc!] 


/* Unique !D for vpb_ID field for unreadable media. */ 


#define UNREAD ID 0x534E4A52L 


* 


/* Stored as (bytes) 0x52,4A,4E,53. */ 


* Unique ID for vpb_ID fieid for damaged volume (recognized by IFS but cannot 


* be normally mounted). 


* 


#define DAMAGED _ID Ox0L 


/* Stored as (bytes) 0,0,0,0. */ 


/* file system dependent - volume params */ 


struct vpfsd { 


char vpd_work[VPDWORKAREASIZE]; /* work area */ 


}; /* vpfsd */ 


/* Current Directory structures */ 


struct cdfsi{ . 
unsigned short cdi_hVPB; 
unsigned short cdi_end; 
char cdi_fiags; 


/* VPB handle for associated device */ 
/* end of root portion of curdir */ 
/* flags indicating state of cdfsd */ 


10 


15 


20 


25 


30 


32 


40 


45 


50 


95 


EP 0 415 346 A2 


char cdi_curdir[CCHMAXPATH]; /* text of current directory */ 
}; /* cdfsi */ : 


/* bit values for cdi_flags (state of cdfsd structure */ 


#define CDI_ISVALID 0x80 /* format is known */ 
#define CDI_ISROOT 0x40 /* cur dir = = root */ 
#define CDI_ISCURRENT 0x20 
struct cdfsd { 

char cdd_work[CDDWORKAREASIZE]; /* work area */ 
}; /* cdfsd */ 


/* Per open-instance (System File) structures */ 


struct sffsi { 
unsigned long sfi_mode; /* access/sharing mode */ 
unsigned short sfi_hVPB; /* volume info. */ 
unsigned short sfi_ctime; /* file creation time */ 
unsigned short sfi_cdate; /* file creation date */ 
unsigned short sfi_atime; /* file access time */ 
unsigned short sfi_adate; /* file access date */ 
unsigned short sfi_mtime; /* file modification time * / 
unsigned short sfi_mdate; /* file modification date * / 
unsigned long sfi_size; /* size of file */ 


unsigned long sfi_position; /* read/write pointer */ 
/* the following may be of use in sharing checks */ 


unsigned short sfi_UID; /* user ID of initial opener */ 
unsigned short sfi_PID; /* process ID of initial opener */ 
unsigned short sfi_PDB; /* PDB (in 3.x box) of initial opener * / 
unsigned short sfi_selfsfn; /* system file number of file instance */ 
unsigned char sfi_tstamp; /* update/propagate time stamp flags */ 
/* use with ST_Sxox and ST_Px« */ 
unsigned short sfi_type; /* use with STYPE */ 
}; /* sfisi */ 


/* sfi_tstamps flags */ 

#define ST SCREAT 1 /* stamp creation time */ 
#define ST PCREAT 2 /* propagate creation time */ 
#define ST SWRITE 4 /* stamp last write time */ 
#define ST PWRITE 8 /* propagate last write time */ 
#define ST SREAD 16 /* stamp last read time */ 
#define ST PREAD 32 /* propagate last read time */ 


/* sfi_ type flags */ 


#define STYPE FILE 0 /* file */ 
#define STYPE_DEVICE1 /* device * / 
#define STYPE_NMPIPE 2 /* named pipe */ 
#define STYPE FCB 4 /* feb sft */ 
/* file system dependent - file instance */ 
struct sffsd { 
char sfd_work{SFDWORKAREASIZE]; /* work area * / 


}; /* sffsd */ 
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/* file system independent - file search parameters */ 
struct fsfsi { 

unsigned short fsi_hVPB; /* volume info. */ 
}; /* fsfsi */ 


/* tile system dependent - file search parameters * / 
#define FSFSD_WORK_SIZE 24 

struct fsfsd { ) 

char fsd_work[FSFSD_WORK_SIZE]; /* work area */ 
}; /* fsfsd */ 


/* file system dependent - device information * / 
struct devisd { a 

unsigned long FSDRef; /* Reference obtained from FSD during ATTACH 
* 


}; /* devisd */ 


Dialed 
* 


* union and structures for FS_FSCTL 


* 


/* pArgType == 1, FileHandle directed case */ 


struct SF { 
struct sffsi far * psffsi: 
struct sffsd far * psffsd; 
} /* SF */ 
/* pArgl ype == 2, PathName directed case */ 
struct CD { 
struct cdfsi far * pcdfsi:; 
struct cdfsd far * pcdfsd; 
char far * pPath; 
unsigned short iCurDirEnd; 
}; /* CD */ 


union argdat { 
/* pArgTlype == 1, FileHandle directed case */ 
Struct SF sf; 


/* pArgi ype == 2, PathName directed case */ 
struct CD cd; 


/* pArglype == 3, FSD Name directed case */ 
/* nothing */ 
}: /* argdat */ 


Yada! 


x 


* Union and structures for FS_NMPIPE 


*/ 


/* Get/SetPHandState parameter block */ 
struct phs_param { 
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short phs_len; 

short phs dlen; - 

short phs pmode; /* pipe mode set or returned */ 
} 


/* DosQNmPipeinfo parameter block, 
* data is info. buffer addr */ 


struct npi_param { 

short npi_len; 

short npi_dlen; 

short npi_level; /* information level desired */ 
hi 


/* DosRawReadNmPipe parameters, 
* data is buffer addr */ 
struct npr_param { 
short npr_len; 
short npr_dien; 
short npr_nbyt; /* number of bytes read */ 


}: 


/* DosRawWriteNmPipe parameters, 
* data is buffer addr */ 
struct npw_param { 
short npw_len; 
short npw_dien; 


short npw_nbyt; /* number of bytes written */ 
} 
/* NPipeWait parameters */ 
struct npq_param { 
short npq len; 
short npq_dien; 
long npq_timeo; /* timeout in milliseconds */ 
short npq_prio; 7* priority of caller * / 
}; 


/* DosCallNmPipe parameters, 

* data is in-buffer addr */ 

struct npx_param { 
short npx_len; 
unsigned short npx_ilen; /* length of in-buffer * / 
char far *npx_obuf; /* pointer to out-buffer */ 
unsigned short npx_olen; /* length of out-buffer */ 
unsigned short npx_nbyt; /* number of bytes read */ 


long npx_timeo; /* timeout in milliseconds */ 
}; 
/* PeekPipe parameters, data is buffer addr */ 
struct npp_param { 

short npp_ten; 


unsigned short npp_dien; 
unsigned short npp_nbyt; /* number of bytes read */ 
unsigned short npp_avi0; /* bytes left in pipe */ 
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unsigned short npp_avit; /* bytes left in current msg */ 
unsigned short npp_ state; /* pipe state */ 
}; 


/* DosTransactNmPipe parameters, 

* data is in-buffer addr */ 

struct npt_param { 
short npt_len; 
unsigned short npt_ilen; /* length of in-buffer * / 
char far *npt_obuf; /* pointer to out-buffer */ 
unsigned short npt_olen; /* length of out-buffer * / 
unsigned short npt_nbyt; /* number of bytes read */ 


}; 


/* QNmpipeSemState parameter block, 

* data is user data buffer */ 

struct qnps_param { 
unsigned short qnps len; /* length of parameter block */ 
unsigned short qnps dien; /* length of supplied data block */ 
long qnps_semh; /* system semaphore handle */ 
unsigned short qnps_nbyt; /* number of bytes returned */ 


}: 

/* ConnectPipe parameter block, no data block */ 

struct npc_param { 
unsigned short npc len; /* length of parameter block */ 
unsigned short npc _dien; /* length of data block */ 

} 

/* DisconnectPipe parameter block, no data block */ 

struct npd_param { 
unsigned short nod len; /* length of parameter block */ 
unsigned short npd_dien; /* length of data block */ 

}: 


union npoper { 
Struct phs_ param _phs; 
Struct npi_param = npi; 
struct npr_ param npr; 
Struct npw_ param npw; 
Structnpq param npq; 
Struct npx_param npx; 
struct npp param npp; 
Struct npt_param = npt; 
Struct qnps param gqnps; 
Struct npc_param npc; 
Struct npd_ param npd; 

}: /* npoper */ 


Dalia 
* 


* Declarations for the FSD entry points. 


* 
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/* bit values for the {Oflag parameter in various FS_ entry points */ 


#define IOFL_WRITETHRU 0x10 /* Write through bit *) 
#define IOFL_NOCACHE 0x20 /* No Cache bit */ 
int far pascal 
FS_ATTACH( 

unsigned short, /* flag . af 

char far *, /* pDev sal | 

void far *, /* if remote drive 

struct vpfsd far * 


else if remote device 
null ptr (OL) */ 


void far *, /* if remote drive 
struct cdfsd far * 
else 
struct devfsd far * */ 
char far *, /* pParm say d 
unsigned short far* /* pLen yf 


); 
/* values for flag in FS ATTACH */ 


#define FSA_ATTACH | 0x00 

#define FSA_DETACH 0x01 

#define FSA_ATTACH_INFO 0x02 

int far pascal 

FS CHDIR( 
unsigned short, /* flag a | 
struct cdfsi far *, /* pcdfsi */ 
struct cdfsd far *, /* pedfsd a 
char far *, /* pDir mf 
unsigned short /* iCurDirEnd */ 


); 
/* values for flag in FS_CHDIR */ 


#define CD_EXPLICIT 0x00 

#define CD_VERIFY 0x01 

#define CD_FREE 0x02 

int far pascal 

FS_CHGFILEPTR( 
struct sffsi far *, /* psffsi* / 
struct sffsd far *, /* psftsd ai 
long, /* offset * 
unsigned short, /* type i 
unsigned short /* \Oflag */ 


); 
/* values for type in FS_CHGFILEPTR */ 


#define CFP_RELBEGIN 0x00 
#define CFP_RELCUR 0x01 

#define CFP_RELEND 0x02 

int far pascal 


FS CLOSE( 


10 


15 


20 


25 


30 


35 


40 


45 


50 


55 


EP 0 415 346 A2 


unsigned short, . /* closetype */ 
unsigned short, /* \Oflag *} 
struct sffsi far *, /* psftsi* / 

struct sffsd far * /* psfisd yf 


); 
#define FS_CL_ ORDINARY 0 
/* ordinary close of file */ 
#define FS_CL_FORPROC 1 
/* final close of file for the process */ 
#define FS_CL_FORSYS 2 
/* final close of file for the system (for all processes) */ 


int far pascal 
FS_COMMIT( 
unsigned short, /* commit type */ 
unsigned short, /* \Oflag = 
struct sffsi far *, /* psftsi*/ 
struct sffsd far * /* psffsd =) 
)i 
/* values for commit type */ 
#define FS_COMMIT_ONE 1 


/* commit for a single file */ 
#define FS_COMMIT_ALL 2 
/* commit due to buf reset - for all files */ 


int far pascal 
FS_COPY( 
unsigned short, /* copy mode */ 
struct cdfsi far *, /* pcdfsi bf 
struct cdfsd far *, /* pedisd sa 
char far *, /* source name */ 
unsigned short, /* iSrcCurrDirEnd af 
char far *, /* pDst ad j 
unsigned short, /* iDstCurrDirEnd af 
unsigned short /* nameType (flags) a 
); 
int far pascal 
FS_DELETE( 
struct cdfsi far *, /* pcdfsi Mf 
struct cdfsd far *, /* pcedfsd ™y 
char far *, /* pFile * / 
unsigned short /* iCurDirEnd */ 


); 


void far pascal 


FS_EXIT( 
unsigned short, /* uid ait 
unsigned short, /* pid */ 
unsigned short /* pdb es 
); 
int far pascal 
FS_FILEATTRIBUTE( 
unsigned short, /* flag af 


struct cdfsi far *, /* pcdfsi a | 
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struct cdfsd far *, /* pedtsd 
char far *, /* pName 
unsigned short, /* iCurDirEnd 


unsigned short far* /* pAttr*/ 
); 


/* values for flag in FS_FILEATTRIBUTE */ 


#define FA_RETRIEVE 0x00 . 

#define FA_SET 0x01 

int far pascal 

FS_FILEINFO( 
unsigned short, /* flag 
struct sffsi far *, /* psftsi* / 
struct sffsd far *, /* psfisd 
unsigned short, /* level */ 
char far *, /* pData 
unsigned short, /* coData 
unsigned short /* \Oflag 


); 
/* values for flag in FS_FILEINFO */ 


#define Fl_ RETRIEVE 0x00 

#define Fl_SET 0x01 

int far pascal 

FS FILEIO( 
struct sffsi far *, /* psttsi*/ 
struct sffsd far *, /* psffsd 
char far *, /* cbCmdList 
unsigned short, /* pCmdLen 
unsigned short far*, /* poError if 
unsigned short /* \Oflag 

); 

int far pascal 

FS_FINDCLOSE( 
Struct fsfsi far *, /* pistsi*/ 
Struct fsfsd far * /* pfsfsd 


); 


/* values for flag in FS_FindFirst, FS_FindFromName, FS_FindNext */ 


#define FF NOPOS 0x00 
#define FF_GETPOS 0X01 
int far pascal 
FS_FINOFIRST( 
struct cdfsi far *, /* pcedfsi 
struct cdfsd far *, /* pedfsd 
char far *, /* pName 
unsigned short, /* iCurDirEnd 
unsigned short, /* attr 
Struct fsfsi far *, /* pfsfsi* / 
struct fsfsd far *, /* pfstsd 


char far *, /* pData 
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unsigned short, /* cbData */ 
unsigned short far*, /* pcMatch +} 
unsigned short, /* level */ 
unsigned short /* flags */ 

int far pascal 

FS_FINDFROMNAME( 
struct fsfsi far *, /* pfsfsi* / 
struct fsfsd far *, /* pfsfsd ail 
char far *, /* pData i 
unsigned short, /* cbData i). 
unsigned short far *, /* pcMatch *} 
unsigned short, /* tevel */ 
unsigned fong, /* position =f 
char far *, /* pName a 
unsigned short /* flags */ 

)i 

int far pascal 

FS_FINONEXT( 
struct fsfsi far *, /* ptsftsi* / 
struct fsfsd far *, /* pfsfsd */ 
char far *, /* pData a & 
unsigned short, /* cbData af 
unsigned short far *, /* pcMatch sf 
unsigned short, /* level */ 
unsigned short /* flag al | 

); 

int far pascal 

FS_FINDNOTIFYCLOSE( 

unsigned short /* handle Be 

)i 

int far pascal 

FS _FINDNOTIFYFIRST( 
struct cdfsi far *, /* pcdfsi a f 
struct cdfsd far *, /* pcedfsd if 
char far *, /* pName st 
unsigned short, /*iCurDirEnd */ 
unsigned short. /* attr * 
unsigned short far*, /* pHandle */ 
char far *, /* pData 7. 
unsigned short, /* cbData tf 
unsigned short far *, /* pcMatch =} 
unsigned short, /* level */ 
unsigned long /* timeout ss 

); 

int far pascal 

FS_FINDNOTIFYNEXT( 
unsigned short, /* handle af 
char far *, /* pData */ 
unsigned short, /* cbData a 
unsigned short far*, /* pcMatch mh 
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unsigned short, /* infolevel =f 
unsigned long /* timeout adj 

); 

int far pascal 

FS_FLUSHBUF( 
unsigned short, /* nhVPB =] 
unsigned short /* flag aff 


); 
/* values for flag in FS_FLUSH */ 


#define FLUSH_RETAIN 0x00 

#define FLUSH_DISCARD 0x01 

int far pascal 

FS_FSCTL( 
union argdat far *, /* pArgdat */ 
unsigned short, /* iArgType a 4 
unsigned short, /* func */ 
char far *, /* pParm */ 
unsigned short, /* lenParm = 
unsigned short far*, /* plenParmOut*/ 
char far *, /* pData =) 
unsigned short, /* tenData a 


unsigned short far* /* pienDataOut */ 
); 


/* values for iArgType in FS_FSCTL */ 
#define FSCTL_ARG_FILEINSTANCE 0x01 
#define FSCTL_ARG_CURDIR 0x02 
#define FSCTL_ARG_NULL 0x03 


/* values for fune in FS_FSCTL */ 

#define FSCTL_FUNC_NONE 0x00 
#define FSCTL_FUNC_NEW_INFO 0x01 
#define FSCTL_FUNC_EASIZE 0x02 


int far pascal 

FS_FSINFO( 
unsigned short, /* flag */ 
unsigned short, /* nVPB af 
char far *, /* pData a 
unsigned short, /* coData oe 
unsigned short /* level */ 


); 
/* values for flag in FS_FSINFO */ 


#define INFO_RETREIVE 0x00 
#define INFO_SET 0x01 
int far pascal 
FS_INIT( 
char far *, /* szParm ad | 
unsigned tong, /* pDevHip af 


unsigned long far * /*pMiniFSD */ 
); 


10 


15 


20 


25 


30 


i ps 


40 


45 


50 


55 


int far pascal 

FS_IOCTL( 
struct sffsi far *, 
struct sffsd far *, 
unsigned short, 
unsigned short, 
char far *, 
unsigned short, 
char far *, 
unsigned short 


) 


int far pascal 

FS_MKDIR( 
struct cdfsi far *, 
struct cdfsd far *, 
char far *, 
unsigned short, 
char far *, 
unsigned short 

); 


int far pascal 

FS MOUNT( 
unsigned short, 
struct vpfsi far *, 
struct vpfsd far *, 
unsigned short, 
char far * 


); 
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/* psffsi* / 

/* psffsd a 
/* cat ws 
/* func a 


/* pParm mE 
/* tenParm tj 
/* pData */ 
/* tenData i 


/* pcdfsi aa: 
/* pcdfsd st f 
/* pName_ a 
/*iCurDirEnd */ 


/*pEABuf = */ 


/* flags */ 

/* flag */ 
/* pvpfsi oe 
/* pvpfsd | 
/* hVPB 

/* pBoot */ 


/* values for flag in FS_ MOUNT */ 


#define MOUNT MOUNT 

‘#define MOUNT_VOL_REMOVED Ox01 
#define MOUNT RELEASE 
#define MOUNT ACCEPT 


int far pascal 

FS MOVE( 
struct cdfsi far *, 
struct cdfsd far *, 
char far *, 
unsigned short, 
char far *, 
unsigned short, 
unsigned short 


); 


int far pascal 

FS NEWSIZE( 
struct sffsi far *, 
struct sffsd far *, 
unsigned long, 
unsigned short 


); 


0x00 

0x02 

0x03 
/* pcdfsi i 
/* pcedfsd aij 
/* psre 7 
/* iSrcCurDirEnd* / 
/* pDst af 

- /* iDstCurDirEnd* / 

/* flags */ 
/* psffsi* / 
/* psffsd 1 3 
/* len af 
/* \Oflag ~) 


*/ 
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int far pascal 
FS_NMPIPE( 
struct sffsi far *, /* psftsi* / 
struct sffsd far *, /* psffsd a 
unsigned short, /* OpType a 
union npoper far *, /* pOpRec =) 
char far *, /* pData */ 
char far * /* pName x} 
); 
/* Values for OpType in FS_NMPIPE */ 
#define NMP _GetPHandState 0x21 
#define NMP _SetPHandState 0x01 
#define NMP_PipeQInfo 0x22 
#define NMP_PeekPipe 0x23 
#define NMP_ConnectPipe 0x24 
#define NMP_DisconnectPipe 0x25 
#define NMP_TransactPipe 0x26 
#define NMP_READRAW Ox11 
#define NMP_WRITERAW 0x31 
#define NMP_WAITPIPE 0x53 
#define NMP_CALLPIPE 0x54 
#define NMP_QNmPipeSemState OxS8 
int far pascal 
FS _OPENCREATE( 
struct cdfsi far *, /* pcdfsi af 
void far *, /* if remote device 
Struct devisd far * 
else 
struct cdfsd far * */ 
char far *, /* pName = 
unsigned short, /*iCurDirEnd */ 
struct sffsi far *, /* psftsi* / 
struct sffsd far *, /* psffsd =} 
unsigned short, /*fhandflag */ 
unsigned short, /* opentiag a | 
unsigned short far*, /* pAction say 
unsigned short, /* attr a 


char far *, 
unsigned short far * 


); 
#define FOC_NEEDEAS 


int far pascal 

FS _PATHINFO( 
unsigned short, 
struct cdfsi far *, 
struct cdfsd far *, 
char far *, 
unsigned short, 
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/* pEABut */ 
/* pigenFiag */ 


Ox1 /*there are need eas for this file */ 


/* flag 

/* pcdfsi 

/* pedfsd 

/* pName 

/* iCurDirEnd 
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unsigned short, /* level */ 
char far *, /* pData 
unsigned short /* cbData 


); 
/* values for flag in FS_PATHINFO */ 


#define P!_ RETRIEVE 0x00 

#define Pi_SET Ox01 ~ 

int far pascal 

FS PROCESSNAME( 
char far * /* pNameBuf 

); 

int far pascal 

FS_READ( 
struct sffsi far *, /* psftsi* / 
struct sffsd far *, /* psffsd 
char far *, /* pData 
unsigned short far*, /* pLen a 
unsigned short /* \Ofiag 

) 

int far pascal 

FS_RMDIR( 
struct cdfsi far *, /* pcdfsi 
struct cdfsd far *, /* pcdfsd 
char far *, /* pName 
unsigned short /* iCurDirEnd 

)i 

int far pascal 

FS_SETSWAP( 
struct sffsi far *, /* psftsi* / 
struct sffsd far * /* psfisd 

); 

int far pascal 

FS SHUTDOWN( 
unsigned short, /* usType 
unsigned long /* ulReserved 


)i 
/* values for usType in FS_ SHUTDOWN */ 


#define SD_ BEGIN 0x00 

#define SD_COMPLETE 0x01 

int far pascal 

FS_WRITE( 
struct sffsi far *, /* psftsi* / 
struct sffsd far *, /* psffsd 
char far *, /* pData 
unsigned short far*, /* pLen a? 
unsigned short /* {Oflag 


*/ 
*/ 


*/ 


et 
*/ 


10 
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35 


int far pascal 

MFS_CHGFILEPTR( 
unsigned long, 
unsigned short 


); 


int far pascal 
MFS_CLOSE( 
void 


); 


int far pascal 
MFS_INIT( 

void far *, 

char far *, 

long far *, 

void far *, 

unsigned long far *, 

unsigned long far * 
); 


int far pascal 
MFS_OPEN( 
char far *, 
unsigned fong far * 
); 
int far pascal 
MFS_READ( 
char far *, 
unsigned short far * 
); 
int far pascal 
MFS_TERM( 
void 


); 
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/* offset a 
/* type a 


/*bootdata */ 
/*numberio */ 
/*vectorrip! */ 


/* bpb */ 
/* pMiniFSD */ 

/* dump address */ 

/* name 

/* size a 

/* data Peas 
/* length =] 


/ 
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APPENDIX lil 


/*static char *SCCSID = “@(#)fsh.h = 1.16 89 /04/18";*/ 
/* fsh.h -FSH_ = fshelper interface declarations */ 


* 


* FSH_DOVOLIO2 omits flag definition 
x 


* Since we are using C5.1, the function prototypes should be made to 
* conform with true ANSI standards. | have converted FSH_ADDSHARE 


* as an example. 


*/ 


#if 1 
int far pascal 
FSH_ADDSHARE( 
char far *, /* pName 
unsigned short, /* mode 
unsigned short, /* hVPB 
unsigned lfong far * /* phShare 
); 
#else 
USHORT far pascal 
FSH_ADDSHARE( 
PSZ pName, 
USHORT mode, 
SHANDLE hVPB, 
LHANDLE phShare 
); 
#endif 


int far pascal 

FSH BUFSTATE( 
char far *, /* pBuf 
unsigned short, /* flag 
unsigned short far* /* pState a 4 


); 


int far pascal 
FSH _CANONICALIZE( 


char far *, /* pPathName 
unsigned short, /* coPathBuf 
char far * /* pPathBuf 


); 


int far pascal 
FSH_CHECKEANAME( 
unsigned short, /* level */ 


unsigned long, /* len of name 
char far * /* pEAName 


); 


int far pascal 
FSH_CRITERROR( 


ie 


*/ 
yi 
*/ 


*/ 
gi 
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int, /* cbMessage */ 

char far *, /* pMessage */ 

int, /* nSubs oF 

char far *, /* pSubs sa 

unsigned short /* fAilowed “/ 
); 
/* Flags for fAllowed 
* 
#define CE ALLFAIL 0x0001 /* FAIL allowed sf 
#define CE_ALLABORT 0x0002 /* ABORT allowed i 
#define CE_ALLRETRY 0x0004 /* RETRY allowed sf 
#define CE_ALLIGNORE 0x0008 /* IGNORE allowed af | 
#define CE_ALLACK  0x0010 /* ACK allowed ad 
/* Return values from FSH_CRITERR 
* 
#define CE_RETIGNORE 0x0000 /* User said IGNORE */ 
#define CE _RETRETRY 0x0001 /* User said RETRY sa 
#define CE RETFAIL 0x0003 /* User said FAIL/ABORT i 
#define CE_RETACK  0x0004 /* User said continue ei} 
int far pascal 
FSH_DEVIOCTL( 

unsigned short, /* FSDRaisedFlag */ 

unsigned long, /* hDev a 

unsigned short, /* sfn a 

unsigned short, /* cat */ 

unsigned short, /* func */ 

char far *, /* pParm ay 

unsigned short, /* cbParm = 

char far *, /* pData i 6 

unsigned short /* cbData */ 
); 
int far pascal 
FSH_DOVOLIO( 

unsigned short, /* operation */ 

unsigned short, /* fAllowed ey 

unsigned short, /* hVPB we 

char far *, /* pData a | 

unsigned short far*, /* pcSec ae | 

unsigned long /* iSec | 
); 
/* Flags for operation 
#define DVIO_OPREAD 0x0000 /* no bit on => readi * / 
#define DVIO_OPWRITE 0x0001 /* ON => write else read =), 
#define DVIO_OPBYPASS 0x0002 /* ON => cache bypass else no bypass 
#define DVIO_OPVERIFY 0x0004 /* ON => verify after write */ 
#define DVIO OPHARDERR 0x0008 /* ON => return hard errors directly */ 
#define DVIO_OPWRTHRU 0x0010 /* ON => write thru .) 
#define DVIO_OPNCACHE 0x0020 /* ON => don't cache data */ 
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/* Flags for fAllowed 
* 


#define DVIO_ALLFAIL 0x0001 /* FAIL allowed */ 


#define DVIO_ALLABORT 0x0002 /* ABORT allowed 
#define DVIO_ALLRETRY 0x0004 /* RETRY allowed 
#define DVIO_ALLIGNORE 0x0008 /* IGNORE allowed 
#define DVIO_ALLACK 0x0010 /* ACK allowed 
int far pascal 
FSH_DOVOLIO2( 
unsigned long, /* hDev “7 
unsigned short, /* sin tf 
unsigned short, /* cat ff 
unsigned short, /* func df 
char far *, /* pParm | 
unsigned short, /* cbParm aif 
char far *, /* pData =) 
unsigned short /* cbData =] 
)i : 
int far pascal 
FSH_FINDCHAR( 
unsigned short, /* nChars af 
char far *, /* pChars a 
char far * far * /* ppStr */ 
); 
int far pascal 
FSH_FINDDUPHVPB( 
unsigned short, /* hVPB ial f 


unsigned short far* /* pHVPB tf 
); 


int far pascal 

FSH_FLUSHBUF( 
unsigned short, /* hVPB sc | 
unsigned short /* fDiscard */ 


); 


/* Discard values 


x 


#define FB_DISCNONE 0x0000 /* Do not discard buffers 
#define FB_DISCCLEAN 0x0001 /* Discard clean buffers 
int far pascal 
FSH_FORCENOSWAP( 
unsigned short /* sel a 
); 
int far pascal 
FSH_GETBUF( 
unsigned long, /* iSec */ 
unsigned short, /* fPreRead a 
unsigned short, /* hVPB al f 


char far * far * /* ppBuf */ 
); 


*/ 
*h 
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/* Flags for fPreRead 
* 


#define GB_PRNOREAD 0x0001 

int far pascal 

FSH_GETOVERLAPBUF( 
unsigned short, /* hVPB 
unsigned tong, /* iSec 
unsigned long, /* iSec 
unsigned long far *, /* pisecBuf a 
char far * far * /* ppBuf 

); 

int far pascal 

FSH_GETVOLPARM( 
unsigned short, /* hVPB 


struct vpfsi far * far *, /* ppVPBfsi */ 
struct vpfsd far * far* /* ppVPBfsd */ 


int far pascal 
FSH_INTERR( 
char far *, /* pMsg 
unsigned short /* cbMsg 
); 


int far pascal 
FSH_ISCURDIRPREFIX( 
char far * /* pName 


); 


void far pascal 
FSH_LOADCHAR( 
char far * far *, /* ppstr 
unsigned short far* /* pChar =/ 
); 


void far pascal 
FSH_PREVCHAR( 


char far *, /* pBeg 
char far * far * /* ppstr 
); 
int far pascal 


FSH_PROBEBUF( 


unsigned short, /* operation 
char far *, /* pData 
unsigned short /* cbData 


)i 


/* Values for operation 
#define PB OPREAD 0x0000 
#define PB_OPWRITE 0x0001 


/* ON => no preread occurs 


*/ 
*/ 


= 


*/ 


*/ 


a 


*/ 
e 
*/ 


af | 


*/ 


a 


es | 


/* Check for read access 
/* Check for write access 


*/ 


*/ 


int far pascal 

.. FSH_QSYSINFO( 
unsigned short, 
char far *, 
unsigned short 


); 


/* Values for index 

* 

#define QSI_SECSIZE 
#define QS!|_PROCID 


1 
2 


#define QSI_ THREADNO 


#define QSI_VERIFY 
int far pascal 
FSH_NAMEFROMSFN( 


unsigned short, 
char far *, 


); 
int far pascal 


4 


FSH_RELEASEBUF (void): 


int far pascal 
FSH_REMOVESHARE( 
unsigned long 


); 


int far pascal 

FSH SEGALLOC( 
unsigned short, 
unsigned long, 
unsigned short far * 


) 


/* Fields for flags 
#define SA_FLDT 
#define SA_FSWAP 


/* pSel 


0x0002 


#define SA FRINGMASK 


#define SA_FRINGO 
#define SA_FRING1 
#define SA_FRING2 
#define SA_FRING3 


int far pascal 
FSH _SEGFREE( 
unsigned short 


)i 


int far pascal 
FSH_SEGREALLOC( 
unsigned short, 


0x0000 
Ox2000 
0x4000 
0x6000 
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/* index sl 
/* pData */ 
/* cbData st 


/* index to query max sector size * / 


/* index to query PID,UseriD and Currentpdb */ 


3 /* index to query abs.thread no */ 
/* index to query per-process verify * / 


/* stn */ 
/* pName */ 


unsigned short far* /*pcbName */ 


/* hShare */ 


/* flags */ 

/* cbSeg */ 
a f 

0x0001 /* ON => alloc LDT else GDT 
/* ON => swappable memory aj 

0x6000 /* mask for tsolating ring 
/* ring O =} 
/* ring 1 as 
/* ring 2 et 
/* ring 3 i 

/* sel of | 

/* sel a 


*/ 


| 
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unsigned long /* cbSeg */ 
)i 


/* Tirneout equates for all semaphore operations 
* . 

#define TO_INFINITE 9 OxFFFFFFFFL 

#define TO NOWAIT Ox00000000L - 


int far pascal 
FSH_SEMCLEAR( 
void far * /* pSem 
); 
int far pascal 
FSH_ SEMREQUEST( 
void far *, /* pSem 
unsigned long /* cmsTimeout */ 
); 
int far pascal 
FSH_SEMSET( 
void far * /* pSem 
) 
int far pascal 
FSH_SEMSETWAIT( 
void far *, /* pSem 
unsigned long /* cmsTimeout */ 
); 
int far pascal 
FSH_SEMWAIT( 
void far *, /* pSem 
unsigned long /* cmsTimeout */ 
); 
int far pascal 
FSH_STORECHAR( 
unsigned short, /* chDBCS ae f 
char far * far * /* ppStr ua 
); 
int far pascal 
FSH_UPPERCASE( 
char far *, /* pName a 
unsigned short, /* cbPathBuf */ 
char far * /* pPathBuf */ 
); 
int far pascal 
FSH_WILDMATCH( 
char far *, /* pPat aif 


char far * /* pStr =) 
); | 


3 


tf 


*/ 


a 
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int far pascal 
FSH_YIELD(void); 


int far pascal 
MFSH_DOVOLIO( 


); 


char far *, 


unsigned short far*, /* cSec 


unsigned long 


int far pascal 
MFSH_INTERR( 


):; 


char far *, 
unsigned short 


int far pascal 
MFSH_SEGALLOC( 


); 


unsigned short, 
unsigned long, 


int far pascal 
MFSH_SEGFREE( 


); 


unsigned short 


int far pascal 


MFSH_SEGREALLOC( 


):; 


unsigned short, 
unsigned long 


int far pascal 
MFSH_CALLRM( 


); 


unsigned long far * 


int far pascal 
MFSH_LOCK( 


); 


unsigned short, 
unsigned long far * 


int far pascal 
MFSH_PHYSTOVIRT( 


); 


unsigned long, 
unsigned short, 
unsigned short far * 


int far pascal 
MFSH_ UNLOCK( 


): 


unsigned long 


unsigned short far* /* Sel 


/* Sel 
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/* Data 
*/ 
/* iSec 


/* Msg 
/* cbMsg 


/* Sel 


/* Sel 
/* cbSeg 


/* Proc 


/* Sel 
/* Handle 


/* Addr 
/* Len 
a 


/* Handle 


*/ 
*/ 


Br 
sf 


*/ 
*/ 


af 


*/ 


ad 


) 
as 


a 


es 


af 


5 
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int far pascal 
MFSH_UNPHYSTOVIRT( 
unsigned short /* Sel 


); 


int far pascal 

MFSH_VIRT2PHYS( 
unsigned long, /* VirtAddr 
unsigned fong far * /* PhysAddr 


oy 


*/ 
*/ 
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APPENDIX IV 


/*** BASEFSD.C 


+ * + # £ 4 4 HO + FH +t F HF HF F FF HH HF FH Ft HF HF HEH HH HH RH HF HH HE HE HH EH RH FH OH 


% 


* *£ ££ © © + 4 FH 


IFS component test FSD 
Copyright 1988, Microsoft Corp. 
Sue Adams 


Description: 
Each entry point in this FSD checks its own tid table to see whether 
or not to save its parameters on behalf of the currently executing 
thread. 


Use: 
The makefile should define a different symbol for each FSD created 
from this source file, so that different FSNAME’S may be used. 


Special Information: 


A table is kept for each thread to place a data buffer (GDT) selector, if 

needed. 

Since the thread number is an absolute system thread number, no semaphore 
is needed on the selector, since a thread can only be executing this code 

in one place at a time. Each thread is limited to one GDT, and when 

finished with it, is expected to free it with the FS_FSCTL entry. 


This implementation keeps one table per/FS_ entry for enabling/disabling 
the saving of incoming parameters on behalf of a thread. 


See TABLE.C for table management routines. 


The FSD will be in an inconsistent state if the system is shutdown via 
DOSSHUTDOWN. The system must be rebooted if other tests are to be run 
using this FSD after the shutdown test. Reason: The flag which allows 

the FSD to distinguish the shutdown test from other tests cannot be reset 
after shutdown. There is no way to communicate with the FSD via FS_FSCTL 
once a DOSSHUTDOWN call is made. This is per 1.2 dcr 259, and as of yet 
has not been decided if FS_FSCTL access will be allowed or not. If it 
becomes the case that FSCTL is accessible, then the ‘pSDdata’ as well as 
‘ls Shutdown _ Test’ flag can be reset to 0 after the shutdown test. If it 

is decided that shutdown will be reversible, then SD_ Status must be reset 
as well. 


Enforced conventions: 


a_i eee ee oe eee 
—_—e ee eee eee eee eee 


The application must enable the appropriate FS_ entry point using 
DOSFSCTL before each FS api call. The entry points will take 
care of disabling themselves each time they are called. 


After an application makes an API call 

that will enter this fsd, if the entry point puts a GDT selector into the 
selector table on behalf of the thread, a subsequent call to DOSFSCTL 
must be made to free the selector and table entry. 
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* Modification History: 
89.07.10 ~ took out ifdefs for DCR509 -- changes enabled in kernel 


version 12.102 (new flags parameter to some entry pts.) 
89.06.23 — added ifdefs for DCRS509 
89.06.20 - added global OpenAction for FS_OPENCREATE to use 
89.05.17 - added support for 1.2 DCR 508: pfgenfiag param to 
FS_OPENCREATE 
89.04.07 ~ integrated basefsd.c and base2fsd.c into one source 
89.03.27 - added define for CCHMAXPATH 
89.02.02 -- added parameter-save-enable capabilities 
89.01.09 - initial version 


* © © ££ © 6 #8 RH 


* 
~ 


#include <doscalls.h> 

#define CCHMAXPATH MAXPATHLEN /* so dont have to include bsedos.h */ 
#include <fsd.h> 

#include <fsh.h> 

#include <error.n> 

#include “boot.h" 

#inciude "basefsd.h" 

#include “table.h" 


* 


* Global Definitions 


x 
#define NULLFEACBLIST (sizeof( ((struct FEAList *)0)->feal_cbList )) 
#define MAXFEACBLIST 2520 3=/* 2520 x 26 (drive letters) fits in 1 seg */ 


#define CalcFEAoff(d) ((unsigned)((char)d - 'A’) * (unsigned)MAXFEACBLIST) 
#define NUMDRIVES 26 
* 
* Forward Declarations 
7 ss Saas aastaasatastaaasas ses SS = 
int init_ FEA_Tab(); 
int DelFEAList(char): 
char ToUpper(char); 
int CopyFEAList(char,struct EAOP far *): 
unsigned Init SHUTDOWN _Data(char far *,char far *); 
void Log _ SD_ _Stats(struct SD_ FS_stats far * ): 
int Getvptsd(unsigned short hVPB): 
int SaveFiags(unsigned short flags); 


extern void int3(): 
extern void far memcop(char far * src, char far * dst, unsigned short count); 


void PopupMsg(char far * Msg); 


* 


* Global Data 


a 


int_acrtused = 0; /* Get rid of the runtime */ 


char FS_NAME[] = FSDNAME; 
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char Version[{] = VERSION; 
char SignOnMsg[] = SIGNONMSG; 


/* FEAsel is only initialized if some test which uses EA's is run */ 
unsigned short FEAsel; /* PUT ASEMAPHORE ON THIS LATER */ 


unsigned EAtype = NICE_EAS;/* returned by FS_OPENCREATE for pfgenflag param */ 


/* OpendAction is returned as the action parameter from FS_OPENCREATE */ 
unsigned OpenAction = FILE_CREATED; /* default action */ 


/* pSDdata is only initialized for fsd234.exe -- testing FS_ SHUTDOWN */ 

struct SD_stats far * pSDdata = LNULL; 

unsigned Is Shutdown Test = INVALID; /* BEWARE! Still set after shutdown */ 
unsigned SD_Status = BEFORE_SD; 


char Ddevisd[sizeof(long)] = DEVFSD_MSG; 
char BadData[sizeof(long)] = “bad”; 
char Dvpfsd[sizeof(struct vpfsd)] = VPFSD_MSG; 


ee, ee 


/*** PopupMsg - send message to user through FSH_CRITERROR 


* ENTRY Msg - message string 
* EXIT -none- 

* RETURN -none- 

* 

void PopupMsg(Msg) 

char far *Msg; 


int rc,MsgLen = 0; 
char far *subs = "\0\0\0": 


while(*(Msg+(MsgLen+ +)) != "\0'); /* get string length */ 


rc = FSH_CRITERROR(MsgLen,Msg,0,subs,CE_ALLABORT); 


/*** FS_INIT - initialization entry 

* ENTRY szParm - command line string from IFS= in config.sys 

sg DevHeip- address of the devhelp callgate 

pMiniFSD - null except when booting from a volume managed by 
an FSD and the exported name of the FSD matches the exported 
name of the mini-FSD. In this case, pMiniFSD will point to 
data established by the mini-FSD (see mFS_INIT) 


EXIT -none- 
RETURN Error code= NO_ERROR 


WARNING: 


+ + 4# &# &# & HH H He HR OH 


* EFFECTS: prints sign on message to stdout at system initialization 
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= initializes data selector/semaphore array 
ee 


int far pascal FS_INIT(szParm, DevHelp, pMiniFSD) 
char far *szParm; 

unsigned long DevHelp; 

unsigned long far *pMiniFSD; 


unsigned short byteswritten; 
int §; 
char ch; 


if (szParm != NULL) 
while (*szParm != '\0') { 
switch (*szParm) { — 

case 'D’: 
int3(); 
break; 

case 'd’: 
int3(); 
break; 


} 


szParm+ +; 


} 


DOSWRITE((unsigned short) 1, 
(char far *)SignOnMsg, 
(unsigned short)(sizeof(SignOnMsg)-1), 
(unsigned far *)&byteswritten ); 


DOSWRITE((unsigned short) 1, 
(char far *)Version, 
(unsigned short) (sizeof(Version)-1), 
(unsigned far *)&byteswritten ); 


Init_EnableFS Tab(); /* initialize RAM semaphores for each FS_entry pt */ 


return NO_ERROR; 


ee ee ee ee ee ee ee 
ee eee ee 


/*** FS FSCTL- exported routine for DOSFSCTL processing 


* 


* ENTRY pArgdat  - points to file system info structs psffsi,psffsd 
= iArgType _ - tells how to interpret pArgdat 

ai func - function code 

. pParm - parameters if needed 

gs lenParm - size of pParm data 

. lenData - size of pData area 

* plenParmOut_ - size of pParm buffer sent back 

* plenDataOut - size of pData buffer sent back 

* EXIT pData - return results in this block 


* 


RETURN Error code 
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* This routine performs many different functions to provide an interface 
* of communication between a ring 3 application and this test FSD. 
WARNING: 
This routine validates the pData buffer, it will be assumed 
that that address remains valid throughout this FSD call. 


* 

x 

* 

* EFFECTS: 
* — If func so specifies, the whole selector table will be invalidated. 

* — This should only be used if a thread/process dies before using this 
* routine to invalidate its table entry. A reboot may be used instead. 
* 


*/ 


int far pascal FS_FSCTL(pArgDat, iArgType, func, pParm, lenParm, 
plenParmOut, pData, lenData ,plenDataOut) 
union argdat far *pArgDat; 
unsigned short iArgType; 
unsigned short func; 
char far * pParm; 
unsigned short lenParm; 
unsigned short far * plenParmOut; 
char far * pData; 
unsigned short lenData; 
unsigned short far * plenDataOut: 
{ 
int rc, index, LName = 0; 
unsigned short sel, off, LSeg; 
FsctiRec far * pBuf; 


rc = FSH_PROBEBUF(WRITEPROBE, (char far *)plenDataOut,sizeof(short)); 
if (rc) { 

PopupMsg("FS_FSCTL: bad plenDataOut pointer’); 

return rc; 


} 
rc = FSH_PROBEBUF(WRITEPROBE. (char far 
*)plenParmOut,sizeof(short)); 
if (rc) { 
PopupMsg("FS_FSCTL: bad plenParmOut pointer’); 
return rc; 


} 
*plenDataOut = *plenParmOut = 0; 


/* we are TESTING this entry point */ 
if (IsEnabled(ENT FSCTL (int far *)&index) ) { 


rc = Disable(ENT FSCTLindex); 
if (rc) return rc; 


/* allocate a GDT selector for returned data */ 
LSeg = sizeof(FsctiRec); 
rc = InitTCBlnstanceData((unsigned short far *)&sel, 
(unsigned short far *)&off, 
(int far *)&index,LSeq); 
if (rc || (index == -1)) goto abort; 


else { 
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/* make a far pointer to the buffer just allocated */ 
pBuf = (FsctlRec far *)MAKEFP(sel,0): 


/* copy this entrypoint's ID into buffer */ 
pBuf-> owner = ENT_FSCTL:; 


/* copy the pArgDat data */ 
switch (iArgType) { 
case 1: /* FileHandle directed case */ 
pBuf->thesffsi = *(pArgDat-> sf.psffsi); 
pBuf->thesffsd = *(pArgDat-> sf.psffsd); 
break; 
case 2: /* PathName directed case */ 
pBuf->thecdfsi = *(pArgDat->cd.pcdfsi); 
pBuf->thecdfsd = *(pArgDat->cd.pcdfsd); 


/* get pName string length + null */ 

while(*(pArgDat->cd.pPath+(LName+ +)) != ‘\0'); 

off = FIELDOFFSET(FsctiRec,pName); 

rc = CopyPararm(sel,(unsigned short far *)&off, 
LName,pArgDat->cd.pPath); 

if (rc) goto abort; 


oBuf->iCurDirEnd = pArgDat->cd.iCurDirEnd: 
break; 
default: break: 


} 


pBuf->iArgType = iArgT ype; 
oBuf->func = func; 
pBuf->pParm = pParm; 
pBut->lenParm = lenParm; 
pBuf->plenParmOut = pienParmOut; 
pBuf->pData = pData: 
pBuf->lenData = lenData; 

pBuf-> pienDataOut = plenDataOut: 


/* we are USING this entry point for communication * / 


switch (func) { /* note no break;'s */ 
case FUNC GET BUF: 
return RetrieveBuf(pData,lenData); 
case FUNC DEL BUF: 
return DeleteTabEntry(): 
case FUNC ENABLE: 
rc = FSH_PROBEBUF(READPROBE,pParm,sizeof(int)); 
if (rc) { 
PopupMsg((char far *)"FS_FSCTL: bad pParm’); 
return rc; 


/*pParm buffer contains the ENT x {D to enable* / 
return Enable( ((int far *)pParm) [0] ); 
case FUNC DISABLE: 
rc = FSH_PROBEBUF(READPROBE, pParm,sizeof(int)): 
if (rc) { 
PopupMsg((char far *)"FS_FSCTL: bad pParm"); 
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retum rc; 


} 
/* pParm buffer contains ENT_x ID to disable */ 
if (isEnabled(((int far *)pParm) [0], 
(int far *)&index)) { 
return Disable(((int far *)pParm) [0], index); 


/* no error if not disabled to begin with * / 
return NO_ERROR; 

case FUNC | INIT_ FEA_SEG: 

/*delete if can figure out how to alloc seg at init * / 
return Init_FEA_ Tab(); 

case FUNC_DEL | FEAST: 

[c= 
FSH_PROBEBUF(READPROBE,pParm,sizeof(char)); 
if (rc) { 
PopupMsg((char far *)"FS_FSCTL: bad pParm’"); 
return rc; 


} 
return DelFEAList(pParm[0}); 
case FUNC_SET_EATYPE: 
rc = FSH_PROBEBUF(READPROBE,pData, 
sizeof(EAtype)); 
if (rc) { 
PopupMsg((char far *)"FS_FSCTL: bad pData’); 
return [c; 
} 
EAtype = *(unsigned far *)pData; 
return NO_ERROR; 
case FUNC SET OPENACTION: 
rc = FSH_PROBEBUF(READPROBE, pData, 
sizeof(OpenAction)); 
if (rc) { 
PopupMsg((char far *)"FS_FSCTL: bad pData’); 
return rc; 
} 
OpenAction = *(unsigned far *)pData; 
return NO_ERROR; 
case FUNC SET SHUTDOWN DATA: 
return Init _ SHUTDOWN _Data(pData,pParm); 
case GET _ERR_ INFO: /* return error code info */ 
return NO_ERROR; 
case GET_MIN_MAX_EA: /* return max/min EA 
sizes * / 
return NO_ERROR; 
case FUNC CLEAR TABLE: /* clear selector table */ 
ClearTabie(Q; 
return NO_ERROR; 
case FUNC_SEL TAB DUMP: 
return SelfabDump(pData,lenData); 
case FUNC _TCB BUF COUNT: 
return GetBufCount(pData,lenData); 
default: 
return FSCTL_ UNKNOWN FUNCTION; 
} /* end switch */ 


EP 0 415 346 A2 


return NO_ERROR; 


abort: 
DeleteTabEntry(); 
return rc; 
} /* FS_FSCTLO */ 
see eeeresn et et ia ee et ses eS et ese eee BBS BB se Esse eses 
mBmeestzseesceeccs Sas aeezescnx=*/ 


/*** FS_ATTACH - attach a remote drive or pseudo character device 
5 J 
ENTRY fiag - 0=attach;1 =detach;2 = query 
pDev - pointer to text of drive: or \dev\device 
pypfsd __ - pointer to vpfsd structure 

pcdfsd - pointer to current directory info 
pParm - address of application parameter area 
pLen - pointer to length of application parameter area 


EXIT -none- 
RETURN NO_ERROR if successful attach/detach; error code if attach ‘fails’ 


w 
® 

2 

® 

* 

dg 

* 

. 

& 

* 

* If enabled: 

* This routine obtains an entry in the thread/GDT selector table, and 
* records whether the 3rd parameter is null or not. When attaching a 
* remote pseudo-character device, this parameter should be null. It should 
* be valid for all other instances. 

* 

2 

® 

* 

® 

* 

" 

® 

® 

* 

* 

= 

* 


If a device is attached, the cdfsd (treated as a DWORD devisd for devices) 
is filled in. This same data should arrive intact to FS_OPENCREATE when 
the device is opened. If a drive is attached, the vpfsd is filled in. 

This same data shouid arrive intact to any FS__ entry recieving an hVPB 
referring to this drive. The cdfsd is also filled in, but with some ‘bad’ 

data, just in case the cdfsd data is passed to OPENCREATE instead of the 
devisd data, when a device is opened. 


WARNING: 
EFFECTS: 


lf we are not testing this entrypoint explicitly, and if detaching a 
drive, any EA's set for this drive are deleted. 


*/ 
int far pascal 
FS ATTACH (flag, pDev. pvpfsd, pcdfsd, pParm, pLen) 
unsigned short flag; 
char far * pDev; 
char far * pvpfsd; 
char far * ocdfsd; 
char far * pParm:; 


unsigned short far* pLen; 


int rc,index: 
unsigned short sel, off, Valid, LSeq =0: 
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if ( IsEnabled(ENT_ATTACH, (int far *)&index) ) { 


rc = Disable(ENT_ATTACH, index); 
if (rc) return rc; 


if (flag == 0) { /* attach */ 
LSeg = sizeof(short) * 2; /* save length & valid flag */ 
rc = InitTCBinstanceData((unsigned short far *)&sel, 
(unsigned short far *)&off, 
10 (int far *)&index,LSeg); 
if (rc || (index == -1)) goto abort; 


if (pvpfsd = = LNULL) { /* attaching device */ 
Valid = INVALID; 
LS /* fill in cdfsd (treated as devisd for a device) */ 
memcop((char far *)Ddevisd, (char far *) pcdfsd, 
sizeof(long)):; 


else { /* attaching drive */ 
20 Valid = VALID; 
/* fill in the vpfsd for drive */ 
memcop((char far *)Dvpfsd,(char far *)pvpfsd, 
sizeof(struct vptsd)); 
* 
25 * fill in cdfsd with “bad” in case it gets sent to 
* opencreate when opening a device instead of being 
* sent ‘devisd’ 
* 
memcop((char far *)BadData, (char far *)pcdfsd, 
30 sizeof(long)); 


} 


/* record whether the 3rd parameter is valid or not */ 
rc = CopyParam(sel,(unsigned short far *)&off, 

35 sizeof(short),(char far *)&Valid); 
if (rc) goto abort: 


return NO_ERROR; /* no error for detach or query */ 
40 } 


/* if detaching a DRIVE, delete (if) any EA’s corresponding to drive* / 
if ((flag == FSA_DETACH) && (pvpfsd != LNULL)) { 
DeiFEAList(pDev[0}); _/* don’t worry if error */ 


45 } 
return NO_ERROR; 
abort: 
DeleteTabEntry(); 
50 return rc; 
} 
FSS SH SSeS SSeS sees sss es SH SH SSS SSeS SSS SSS SSS SSS SS SHSs 
/*** FS_OPENCREATE -- open/create file entry point 
55> = 


* FS_OPENCREATE(pcdfsi, pcdfsd, pName, iCurDirEnd, psffsi, psffsd, 
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fhandflag, openfiag, pAction, attr, pEABuf) 


ENTRY  - pcdfsi -> file system independent working directory struct 
pcdisd -> file system dependent working directory struct 
pName -> asciiz name of file 
iCurDirEnd = index of hte end of the current directory in pName 
Psffsi -> file system independent portion of file instance 
psffsd -> file system dependent portion of file instance 
fhandflag = desired sharing mode and access mode 
openfiag = action taken when the file is present or absent 
pAction -> action taken variable 
attr = OS/2 file attributes 
pEABuf -> extended attribute buffer 

EXIT -returns NO_ERROR because this is a FAKE OpenCreate. 


Named pipe considerations: 
THIS CALL DOES NOT DO AN OPEN. It is merely a means of 
opening a named pipe without making or connecting it first 


If enabled: 
This routine copies its first 2 parameters to a TCB instance data area 
for verification 


In general: 

EAs may be set on a per-drive basis - i.e. all files pertaining 

to a particular drive will have the tast EA list set for any file on 

the same drive (if any). So, care must be taken if setting different 
EA lists for files on the same drive - be sure the EA’s you set are 
not cancelled out by a subsequent DOSOPEN2’s. 

Sffsi and sffsd are filled in with some bogus values. The action 
returned is always file-created. 


int far pascal 
FS OPENCREATE(pcdfsi, pcdfsd, pName, iCurDirEnd, psffsi, psffsd, fhandflag, 


openflag, pAction, attr, pEABuf , pfgenfiag) 


struct cdfsi far * pcdfsi; 

“ char far * pcdfsd: 
char far * pName: 
unsigned short iCurDirEnd; 
struct sffsi far * psffsi; 
struct sffsd far * psftsd; 
unsigned short fhandflag; 
unsigned short openfiag; 
unsigned short far * pAction; 
unsigned short attr; 
char far * pEABuf; 


unsigned short far * pfgenfiag; 


int rc, index, fsdrc = NO_ERROR; 
unsigned short FEAoff, sel, off, Valid, Lseg=0; 
struct FEAList far *temp; 


if (IsEnabled(ENT_OPENCREATE (int far *)&index) ) { 


rc = Disable(ENT_OPENCREATE, index); 
if (rc) return rc; 
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/* get the length of the GDT segment needed */ 

LSeg = sizeof(GenericRec); 

rc = InitTCBinstanceData((unsigned short far *)&sel, 
(unsigned short far *)&off, 
(int far *)&index,LSeg); 

if (re | | (index == -1)) goto abort; 


/* record whether the 1st parameter is valid or not */ 

Valid = (pcdfsi = = LNULL) ? INVALID : VAUD; 

rc = CopyParam(sel, (unsigned short far *)&off, 
sizeof(short), (char far *)&Valid); 

if (rc) goto abort; 


/* copy the contents of the devisd field (cdfsd parameter) */ 
rc = CopyParam(sel, (unsigned short far *)&off, 

sizeof(long), (char far *)pcdfsd); 
if (rc) goto abort; 


*pAction = OpenAction; /* action set via FSCTL */ 
/* if we set action to undefined, then we want to explicitly fail * / 
if (OpenAction == UNDEFINED ACTION) fsdrc = ERROR_OPEN_FAILED; 


*pfgenfiag = EAtype; 


/* this can be set via FSCTL */ 


/* is this a file name? */ 
if (pNamef{1} == °:’) { 


psffsi->sfi_type = STYPE_FILE; 


* fill in the first byte of sffsd with current drive letter 
* if this is a file - cheap way to let FS_FILEINFO know what 
* drive a file refers to. Assuming the next file queried is 


* the one opened here... 
* 


psfisd->sfd_work(O] = pcdfsi->cdi_curdir[0); 
psfisd->sfd_work([1] = ‘\0’: 


* 


* Set extended attributes — 

* if DOSOPEN2 sends in OL for pEAbuf, the kernel sets the 

* RPL bits in the SELECTOR to reflect ring3 protection level; 

* so mask off bits 0&1 of the selector before checking for 

* NULL. 

if ((unsigned long)pEABuf & (~0x00030000)) { /*pEABuf not null*/ 
rc = FSH_PROBEBUF(READPROBE,pEABuf,sizeof(struct 


if (rc) { 
PopupMsg((char far *)"FS_OPEN:bad pEABuf"); 
return rc; 


/* calculate offset into the FSD’s per/drive FEA table* / 
FEAoff = CalcFEAoff(pName{0}); 
temp = ((struct EAOP far *)pEABuf)->fpFEAList; 
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if ((unsigned short)(temp->feal_cbList) > MAXFEACBLIST) { 


fsdre = FSD_FEALIST TOO_LONG; 


} 
else { 
CopyParam(FEAsel, (unsigned short far *)&FEAoff, 
(unsigned short) (temp->feal_cbList), 
(char far *)temp); 
} 


/* is it a device? */ 


else if ((pName[1} == 'D’)&&(pName[2] = = 'E')&&(pName[3] == Ae { 


psffsi->sfi_type = STYPE_ DEVICE; 


/* must be a named pipe */ 


elise { 
psffsi->sfi_type = STYPE_NMPIPE; 
/* fill in first byte of sffisd */ 
psffsd->sfd_work{0] = BOGUS WORK_CHAR; 
psfisd->sfd_work[1]} = *\0'; 

} 


/* fill in some fields of the sffsi with a bogus value * / 
psffsi->sfi_ctime = BOGUS _CTIME; 

psffsi->sfi_ cdate = BOGUS CDATE; 
psffsi->sfi_atime = BOGUS . ~ATIME; 

psffsi-> sfi_ adate = BOGUS | ADATE; 

pstfsi->sfi_ mtime = BOGUS _ MTIME; 

psffsi->sfi_ mdate = BOGUS _ MDATE; 

psffsi- ->sfi_ i size = (long)BOGUS _ SIZE; 
psfisi->sfi_position = (long)BOGUS POS; 


if (Is_Shutdown_Test) Log SD_Stats(&(pSDdata->Open_stats)); 


return fsdrc: 


DeleteTabEntry(Q: 
return Ic; 


/*** FS _FILEINFO — returns information for a specific file 


* EXIT -none- 


* RETURN NO | 


* If enabled: 


ENTRY flag - indicates retrieval vs. setting of information 


psffst - pointer to file system independent data 

psffsd - pointer to file system dependent data 

level §- information level to be returned 
pData - address of application data area 

cbData - length of the application data area 
lOflag - per handle flag 


ERROR if successful 
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* 


* WARNING: 


* EFFECTS: EA's will always be returned for query of level 4 
* 
int far pascal 
FS_FILEINFO(flag, psffsi, psffsd, level, pData, cbData, !Oflag) 
unsigned short flag; 
struct sffsi far * psffsi; 
struct sffsd far * psffsd; 
unsigned short level; 
char far * pData: 
unsigned short cbData; 
unsigned short lOflag; 
{ 
int rc, index; 
unsigned short sel, off, LSeg; 
FilelnfoRec far * pBuf; 
if ( sEnabled(ENT_FILEINFO, (int far *)&index) ) { 
rc = Disable(ENT_FILEINFO,index); 
if (rc) return re; 
/* allocate a GDT selector for returned data */ 
LSeg = sizeof(FilelnfoRec); 
rc = InitTCBinstanceData((unsigned short far *)&sel, 
(unsigned short far *)&off, 
(int far *)&index,LSeg); 
if (rc || (index == -1)) goto abort; 
pBuf = (FileinfoRec far *)MAKEFP(sei,0); 
pBuf->owner = ENT_FILEINFO; 
pBut-> flag = flag; 
pBuf->thestfsi = *psffsi; 
pBuf->thesfisd = *psffsd; 
pBuf-> level = level: 
pBuf->pData = pData: 
/* cbData should be cbList (of FEA list) + sizeof EAOP */ 
pBuf->cbData = cbData: 
pBuf->lOflag = IOflag; 
/* always copy the FEA list for retrieval of level 4 info */ 
if ((flag == 0) && (level == 4)) { 
/*if sfd_work is trashed-use FSH_NAMEFROMSEFEN with LDT buf*/ 
return CopyFEAList(psffsd->sfd_work{O], 
(struct EAOP far *)pData); 
} 
else return NO_ ERROR; 
abort: 
DeleteTabEntry(); 
return rc; 
} 
/*S SSS SSS SSS Se SH sees SSS SS SSS SSS SSS SSS HSS SSeS SS SSs 
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/*** FS_PATHINFO - get/set a file's informations 


* 
* ENTRY flag - retrieve =0;: set=1; all other values reserved 
= pcdfsi - ptr to file system independent curdir data 
pcdisd - ptr to file system dependend curdir data 
~ pName - ptr to name of file or directory 
: iCurDirEnd - index of the end of the curdir in pName 
* level - level of info to return in pData 
= pData ' + ptr to application data area 
i cboData - length of application data area 
* EXIT pData - filled with requested info (if flag = 0) 
* RETURN 
* WARNING 
* EFFECTS: 
* EA's will always be returned for query of level! 4 
* 
* 
* 
*/ 
int far pascal 
FS_PATHINFO(flag, pcdfsi, pedfsd, pName, iCurDirEnd, level, pData, cbData) 
unsigned short flag; 
struct cdfsi far * pcdfsi; 
struct cdfsd far * pcdfsd; 
char far * pName; 
unsigned short iCurDirEnd; 
unsigned short level; 
char far * pData; 
unsigned short cbData; 
{ 
int rc, index; 
unsigned short sel, off, LSeg, LName = 0; 
PathinfoRec far * pBuf; 


if (IsEnabied(ENT PATHINFO, (int far *)&index) ) { 


rc = Disable(ENT_PATHINFO, index); 
if (rc) return rc; 


/* allocate a GDT selector for returned data */ 
LSeg = sizeof(PathinfoRec); 
rc = Init? CBinstanceData((unsigned short far *)&sel, 
(unsigned short far *)&off, 
(int far *)&index,LSeg); 
if (rc || (index == -1)) goto abort; 


pBuf = (PathInfoRec far *)MAKEFP(sel,0); 


pBuf->owner = ENT PATHINFO; 
pBuf-> flag = flag; 
pBuf->thecdfsi = *pcdfsi: 
pBuf->thecdfsd = *pcdfsd; 


/* copy the pName parameter * / 
off = FIELDOFFSET(PathinfoRec,oName); 
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while(*(pName+(LName+ +)) != "\0’); /* get the name length */ 
rc = CopyParam(sel, (unsigned short far *)&oiff, 

LName,pName); sy 
if (rc) goto abort; 


pBuf->iCurDirEnd = iCurDirEnd; 
pBuf->level = level; 
pBuf->pData = pData:; 
pBuf->cbData = cbData: 


} 


/* always copy the FEA list for retrieval of level 4 info */ 
if (flag == 0) && (level == 4)) { 
return CopyFEAList(pName[0],(struct EAOP far *)pData); 


} 
else return NO_ERROR; 


abort: 
DeleteTabEntry(); 
return rc; 
} 
Pees sSasSeoreslseoeesese eee e esos esses Ssscesssse=5 
Sesser sssessessessssseseea*/ 
int far pascal 


FS SHUTDOWN (type,reserved) 
unsigned short type; 
unsigned long reserved; 


#if defined(generic) 


* 


* If reserved is not 0, it will be recorded in the pSDdata segment. 

* if itis bad on > 1 call, the last bad value received will be 

* reflected when the data is retrieved by the ring test. 

if (reserved != OL) { 
pSDdata->General_stats.FS_SD_bad_reserved = reserved; 

} 


switch (type) { 
case SHUTDOWN. START:{ 


SD Status = DURING SD; 
/* signal the ring3 test's worker threads to begin */ 
if (pSDdata != LNULL) { 

FSH SEMCLEAR((char far *)pSDdata- 


>General_stats.Signal SD RAM sem); 
} 


break; 


J 

case SHUTDOWN _END: { 
SD_Status = AFTER_SD; 
break; 
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default: { 
/* the last bad type param received will be recorded */ 
pSDdata->General_stats.FS_SD_bad_type = type; 


} 

}/* switch */ 

/* record the thread which called FS_ SHUTDOWN */ 

if (pSDdata != LNULL) { /* only if the test is calling us.. */ 
Log SD_Stats(&(pSOdata->Shutdown_stats)); 
/* allow other threads to run */ 
FSH_YIELDQ; 


} 
/* even if a param is bad, return 0; error will be recorded in GDT */ 


return NO_ERROR; 


/* return the uppercase of an alphabetic character, else return 0 */ 
char ToUpper(letter) 
Char letter; 


{ 
if (SBETWEEN(‘A’,'2Z’,letter)) return letter; 


else if (ISBETWEEN(‘a’,'z’ letter)) return (letter - ‘a’ + ‘A’); 
else return 0x00; 


* ENTRY none 
RETURN: appropriate error code 


WARNING: 

If multiple threads (processes) will be accessing the same FSD built 
from this file, a semaphore must be added to the section of code as 
indicated. We only want the GDT selector to be allocated once. 


EFFECTS: 
The FSD will allocate itself a GDT segment to use for storing FEA lists 
ona per/drive (not per/file) basis. The GDT biock is divided into 
NUMDRIVE sub-blocks. Each drive has MAXFEACBLIST bytes 

in which to store its FEA list. Initially, each FEA list is empty. This 

is indicated by storing the sizeof the cbList field of an FEA list in the 
first bytes of each sub-block. This GOT segment is only allocated if 
a test application explicitly instructs it (via FS_FSCTL). 


* 4£* © &* &* #@ ££ & # 4H MH 8 OH OH UM OU 


/* long size is hardcoded here for cblist */ 
int Init_FEA_TabQ) 
{ 

char far * FEATab; 

int i = 0, rc; 

unsigned FEAoff; 
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*== = =HEY!!! GET A SEMAPHORE====*/ 

if (FEAsel != 0) return FEA_SEGMENT_EXISTS; 

/* allocate a ring 0, GODT, nonswappable segment selector */ 

rc = FSH_SEGALLOC(0x0000, (long) (MAXFEACBLIST *NUMDRIVES), 

(unsigned short far *)&FEAsel); 
/t====HEY!!! RELEASE THE SEMAPHORE = = = =*/ 
. if (rc) return rc; 

for (i='A';i< ="Z'si+ +) { 
FEAoff = CalcFEAoff(i); 
FEATab = (char far *)MAKEFP(FEAsel,FEAoff); 
((unsigned long far *}FEATab)[0] = (long)NULLFEACBLIST; 


retum NO ERROR; 


/***DelFEAList - mark the FEA list for a drive as empty 

ENTRY drive - which drive to mark an empty FEA list for 

EXIT 

RETURN appropriate error code 

WARNING: 

EFFECTS: 

The first bytes of the appropriate sub-block of the FSD's FEA segment 
is marked with the sizeof the cbList field of an FEAlist. This indicates 
that the list is empty, i.e. only is long enough to hold the length of 

the field itself, which indicates the length of the list. 


* © 8 + # HM Hh He OH OH 


® 


int DelFEAList(drive) 
char drive; 


{ 
char far * FEATab, updrive; 


if ((updrive = ToUpper(drive))) return ERROR_INVALID DRIVE: 

if (FEAsel != 0) { 
FEATab = (char far *)/MAKEFP(FEAsel, CalcFEAoff(updrive)): 
((unsigned tong far *)FEATab)[0] = (long)NULLFEACBLIST; 
return NO_ERROR; 


} 
else return NULL. FEA SELECTOR; 


/***CopyFEAList - copy the FEA sub-block for this drive to an FEA buffer 
ENTRY drive - which drive should we get the FEA list for? 
pEAOP - pointer to an EAOP list which holds the pointer 
to the FEA buffer we will copy our FEA list to 
EXIT 
RETURN 
WARNING: FEA lists are limited to 64k in OS/2 version 1.2 
EFFECTS: 


* 4@ + © #@ @ & 8 8 


An EAOP structure contains a pointer to an FEA list buffer. It is 
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/* === =HEY!!! GET A SEMAPHORE = = = =*/ 
if (FEAsel != 0) return FEA_SEGMENT_EXISTS; 
/* allocate a ring 0, GDT, nonswappabie segment selector */ 
rc = FSH_SEGALLOC(0x0000, (long) (MAXFEACBLIST*NUMDRIVES), 
(unsigned short far *)&FEAsel); 
/*====HEY!!! RELEASE THE SEMAPHORE = = = =*/ 
. if (rc) return cc; 
for (i="A'si< ="Z'si+ +) { 
FEAoff = CalcFEAoff(i); 
FEATab = (char far *)MAKEFP(FEAsel,FEAoff); 
((unsigned tong far *)FEATab) [0] = (long)NULLFEACBLIST: 


retum NO ERROR; 


/***DelFEAList — mark the FEA list for a drive as empty 


ENTRY drive - which drive to mark an empty FEA list for 

EXIT 

RETURN appropriate error code 

WARNING: 

EFFECTS: 

The first bytes of the appropriate sub-block of the FSD's FEA segment 
is marked with the sizeof the cbList field of an FEAlist. This indicates 
that the list is empty, i.e. only is long enough to hold the length of 

the field itself, which indicates the length of the list. 


* 2© 8© 4#@ @ & 4H #8 RH MH 8 
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int DelFEAList(drive) 
char drive; 


{ 
_ Char far * FEATab, updrive; 


if (((updrive = ToUpper(drive))) return ERROR_INVALID_ DRIVE: 

if (FEAsel ! = 0) { 
FEATab = (char far *)MAKEFP(FEAsel, CalcFEAoff(updrive)): 
((unsigned long far *)FEATab)(0} = (long)NULLFEACBLIST; 
retum NO_ ERROR; 


} 
else return NULL FEA SELECTOR; 


/***CopyFEAList -- copy the FEA sub-block for this drive to an FEA buffer 


ENTRY drive - which drive should we get the FEA list for? 
pEAOP - pointer to an EAOP list which holds the pointer 
to the FEA buffer we will copy our FEA list to 
EXIT 
RETURN 
WARNING: FEA lists are limited to 64k in OS /2 version 1.2 
EFFECTS: 


* 4 4%© © © 8 8 8 OM 


An EAOP structure contains a pointer to an FEA list buffer. It is 
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* this pointer that will be used as the destination of the FEA list copy. 
* The appropriate source FEA list will be calculated from ‘drive’ and 
* the FSD's FEA segment. . 


* 

int CopyFEAList(drive, pEAOP) 
char drive; 

struct EAOP far * pEAOP; 


{ 
int rc; 


struct FEAList far * dest; 
char far * source; 
unsigned count; 


rc = FSH_PROBEBUF(READPROBE, (char far *)pEAOP, sizeof(struct 
EAOP)); 
if (rc) { 
PopupMsqg((char far *)"CopyFEAList: bad pEAOP"); 
return rc; 


} 


dest = pEAOP->fpFEAList; 
/* note conversions from long to short for version 1.2 */ 
rc = FSH_PROBEBUF(WRITEPROBE, (char far *)dest, 
(unsigned short)(dest->feal_cbList)); 
if (rc) { 
PopupMsa((char far *)“CopyFEAList: bad fpFEAList’); 
return rc; 


} 


source = (char far *)MAKEFP(FEAsel,CalcFEAoff(drive)); 
count = (unsigned short)(((unsigned long far *)source){[0]); 


/* EA lists are restricted to 64k in 1.2 */ 

if ((unsigned short)(dest->feal_cbList) < count) { 
return ERROR BUFFER OVERFLOW; 

} 


memcop(source, (char far *)dest,count); 
retum NO_ ERROR; 


} 


unsigned Init SHUTDOWN_Data(pGDT_sel,pCBsel) 
char far * pGDT sel; 
char far * pCBsel: 


{ 


unsigned rc; 


rc = FSH_PROBEBUF(WRITEPROBE,pGDT sel,sizeof(short)); 


if (rc) { 
PopupMsg((char far *)"Init_ SHUTDOWN Data:bad pGDT sel"); 


return rc; 


} 
rc = FSH_PROBEBUF(READPROBE, pCBsel,sizeof(short)); 


if (rc) { | 
PopupMsq((char far *)"Init SHUTDOWN_Data:bad pCBsel"); 
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pBuf = (CommitnCloseRec far *)MAKEFP(seli,0); 


pBuf->owner = ENT COMMIT: 
pBuf->type = type; 
pBuf->lOfiag = lOfiag; 

} 


if (is Shutdown Test) Log SD_Stats(&(pSDdata->Commit_stats)); 
return NO_ERROR; 
abort: 
DeleteTabEntry(Q); 
return rc; 


} 


int far pascal 

FS_READ(psfisi, psffsd, pData, pLen, IOflag) 
struct sffsi far * psifsi; 
struct sffsd far * psffsd; 
char far * pData; 
unsigned short far* pLen; 
unsigned short lOfiag; 


int rc, index; 


if (sEnabled(ENT READ, (int far *)&index) ) { 
rc = Disable(ENT_ READ, index); 
if (rc) return rc; 
return SaveFiags(IOfiag); 

} 


if (Is Shutdown Test) Log _SD_Stats(&(pSDdata->Read_stats)); 
return NO_ERROR; 
} 


int far pascal 

FS_WRITE(psffsi, psfisd, pData, pLen, |Oflag) 
struct sffsi far * psffsi: 
struct sffsd far * psffsd: 
char far * pData: 
unsigned short far* plLen; 
unsigned short lOflag; 


int rc, index; 


if (IsEnabled(ENT WRITE, (int far *)&index) ) { 
rc = Disable(ENT_ WRITE, index); 
if (rc) return rc; 
return SaveFlags(IOflag); 

} 


if (is Shutdown Test) Log SD_Stats(&(pSDdata->Write_stats)); 
return NO_ERROR; 
} 


int far pascal 
FS_DELETE(pcdfsi, pcdfsd, pFile, iCurDirEnd) 
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struct cdfsi far * pcdfsi; 
struct cdfsd far * pcdfsd; 
char far * pFile; 
unsigned short iCurDirEnd; 
{ 
if (is Shutdown Test) Log SD_Stats(&(pSOdata->Delete_stats)); 
return NO_ERROR; 
} 
int far pascal 
FS FLUSHBUF(hVPB, flag) 
unsigned short hVPB; 
unsigned short flag; 
{ 
int rc, index; 
if (IsEnabled(ENT FLUSHBUF, (int far *)&index) ) { 
rc = Disable(ENT_FLUSHBUF, index); 
if (rc) return rc; 
return Getvpfsd(hVPB); 
} 
if (is_ Shutdown Test) Log SD_Stats(&(pSDdata->Flushbuf_stats)); 
return NO_ERROR; 
} 
int far pascal 
FS_CHDIR(fiag, pcdfsi, pedfsd, pDir, iCurDirEnd) 
unsigned short flag; 
struct cdfsi far * pcdisi; 
Struct cdfsd far * pcdfsd; 
char far * pDir; 
unsigned short iCurDirEnd; 
{ 
if (is Shutdown Test) Log SD_Stats(&(pSDdata->Other_stats)); 
return NO_ERROR; 
} 
int far pascal 
FS CHGFILEPTR(psffsi, psffsd, offset, type, |Oflag) 
struct sffsi far * psffsi; 
struct sffsd far * psffsd; 
long offset; 
unsigned short type; 
unsigned short lOflag; 
{ 


int rc, index; 


if (IsEnabled(ENT CHGFILEPTR , (int far *)&index) ) { 
rc = Disable(ENT CHGFILEPTR, index); 
if (rc) return rc; 
return SaveFlags(!Oflag); 

} 


if (Is Shutdown_Test) Log SD_Stats(&(pSDdata-> Other _stats)); 
return NO_ERROR; 
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} 
int far pascal 
FS_CLOSE(type, iOflag, psffsi, psffsd) 
unsigned short type; 
unsigned short iOfiag; 
struct sffsi far * pstftsi; 
struct sffsd far * psffsd; 
{ 
int rc, index; 
unsigned short sel, off, LSeg;: 
CommitnCloseRec far * pBuf: 
if ( IsEnabled(ENT_ CLOSE, (int far *)&index) ) { 
tc = Disable(ENT CLOSE, index); 
if (rc) return rc; 
LSeg = sizeof(CommitnCloseRec): 
rc = initTCBinstanceData((unsigned short far *)&sel, 
(unsigned short far *)&off, 
(int far *)&index,LSeq): 
if (rc | | (index = = -1)) goto abort; 
pBuf = (CommitnCloseRec far *)MAKEFP(sel,0); 
pBuf->owner = ENT CLOSE; 
pBuf->type = type; 
pBut->iOflag = iOflag; 
} 
if (is_Shutdown_Test) Log SD_Stats(&(pSDdata->Other_stats)); 
return NO_ERROR; 
abort: 
DeleteTabEntry(Q: 
return rc; 
} 
int far pascal 
FS_COPY(mode, pcdfsd, pedfsi, pSre, iSrcCurDirEnd, pDst, iDstCurDirEnd, flags) 
unsigned short mode; 


struct cdfsi far * pcdfsd: 

Struct cdfsd far * pcdfsi: 

char far * pSrc; 

unsigned short iSrcCurDirEnd; 
char far * pDst: 

unsigned short iDstCurDirEnd; 
unsigned short flags; 


if (Ils_Shutdown Test) Log SD_Stats(&(pSDdata->Other_stats)); 
return(ERROR_CANNOT_ COPY); 


I 


void far pascal 

FS_EXIT(uid, pid, pdb) 
unsigned short uid; 
unsigned short pid; 
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unsigned short pdb; 
{ : 
if (is Shutdown Test) Log SD_Stats(&(pSDdata->Other_stats)): 
5 =} 
int far pascal 
FS_FILEATTRIBUTE(fiag, pcdfsi, pcdfsd, pName, iCurDirEnd, pAttr) 
unsigned short flag; 
10 struct cdfsi far * pcdfsi; 
struct cdisd far * pcdfsd; 
char far * pName; 
unsigned short iCurDirEnd; 
unsigned short far * pAttr,; 
15 { 
if (Is Shutdown _Test) Log SD_Stats(&(pSDdata->Other_stats)); 
return ERROR_NOT_SUPPORTED; 
} 


20 _ int far pascal 
FS _FILE!O(psffsi, psfisd, pOmdList, pCmdLen, poError, [Oflag) 


Struct sffsi far * psffsi; 
struct sffsd far * psffsd; 
char far * pCmdList; 
25 unsigned short pCmdLen; 
unsigned short far* po€Error; 
unsigned short lOfiag; 
{ 
int rc, index; 
30 
if ( lsEnabled(ENT_FILEIO, (int far *)&index) ) { 
rc = Disable(ENT_FILEIO,index); 
if (rc) return rc; 
return SaveFlags(!Oflag); 
35 } 
if (Is Shutdown Test) Log SD_Stats(&(pSDdata->Other_stats)); 
retum ERROR NOT SUPPORTED; 
} 
40 
int far pascal 
FS_FINDCLOSE (pfsfsi, pfsfsd) 
struct fsfsi far * pfsfsi: 
struct fsfsd far * pfsfsd; 
45 { 
if (Is_ Shutdown Test) Log SD_Stats(&(pSDdata->Other_stats)); 
return ERROR NOT SUPPORTED; 
} 
50 
int far pascal 
FS_FINDFROMNAME(pfsfsi, pfsfsd, pData, cbData, pcMatch, level, position, 
pName, flags) 
struct fsfsi far * pfsfsi: 
55 struct fsfsd far * pfsfsd; 


char far * pData; 
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unsigned short cbData; 
unsigned short far* pcMatch: 
unsigned short level; 
unsigned long position; 
char far * pName; 
unsigned short flags; 
{ 
if (is Shutdown_Test) Log SD_Stats(&(pSDdata->Other_stats)); 
return ERROR _NOT_ SUPPORTED; 
} 
int far pascal 
FS _FINDFIRST(pcdfsi, pedfsd, pName, iCurDirEnd, attr, pfsfsi, pfsfsd, pData, cbData, 
pcMatch, level, flags) 
Struct cdfsi far * pcdfsi; 
struct cdfsd far * pcdfsd; 
char far * pName; 
unsigned short iCurDirEnd; 
unsigned short attr; 
struct fsfsi far * pfsfsi; 
struct fsfsd far * pfsfsd; 
char far * pData; 
unsigned short cbData; 
unsigned short far* pcMatch: 
unsigned short level: 
unsigned short flags; 
{ 
if (is_Shutdown Test) Log SD_Stats(&(pSDdata-> Other stats); 
return ERROR NOT. SUPPORTED: 
} 
int far pascal 
FS_FINONEXT (pfsfsi, pfsfsd, pData, cbData, pcMatch, lovee flag) 
struct fsfsi far * pfsfsi; 
struct fsfsd far * pfsfsd; 
char far * pData; 
unsigned short cbData; 
unsigned short far* pcMatch; 
unsigned short level; 
unsigned short flag; 
{ 
if (is Shutdown Test) Log SD_Stats(&(pSOdata->Other_stats)); 
return ERROR _NOT _ SUPPORTED: 
} 
int far pascal | 
FS_FSINFO(flag, hVPB, pData, cbData, level) 
unsigned short flag; 
unsigned short hVPB; 
char far * pData: 
unsigned short cbData; 
unsigned short level: 
{ 
int rc, index; 
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if ( IsEnabled(ENT_FSINFO, (int far *)&index) ) { 
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rc = Disable(ENT_FSINFO meen): 


if (rc) return rc; 
return Getvpfsd(hVPB); 


} 


if (Is Shutdown Test) Log SD Stats(&(pSDdata->Other_stats)); 


retum ERROR | NOT | SUPPORTED; 


} 
int far pascal 
FS lOCTL(psffsi, psffsd, cat, func, pParm, lenParm, pData, lenData) 
struct sffsi far * psffsi; 
struct sffsd far * psffsd; 
unsigned short cat; 
unsigned short func; 
char far * pParm; 
unsigned short lenParm; 
char far * pData; 
unsigned short lenData; 
{ 
return ERROR_NOT_ SUPPORTED; 
} 
int far pascal 


MFS_CHGFILEPTR( 
unsigned long offset, 
unsigned short type 


) 
{ 
} 


int far pascal 
MFS_CLOSE( 


{ 
} 


int far pascal 
MFS_INIT( 
void far * bootdata, 
char far * number _io, 
long far * vectorripl, 
char far * bpb, 
unsigned long far* pMiniFSD, 
unsigned tong far * dumpaddr 


) 
{ 
} 


int far pascal 
MFS OPEN( 
char far * name, 
unsigned long far* size 


return ERROR_NOT_SUPPORTED; 


return ERROR NOT SUPPORTED; 


return ERROR_NOT_ SUPPORTED; 
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return ERROR_NOT_SUPPORTED; 


} 


int far pascal 
MFS READ( 


char far * data, 
unsigned short far * length 


) 


return ERROR_NOT_SUPPORTED; 


} 
int far pascal 
MFS_TERM( 
return ERROR NOT SUPPORTED; 
} 
int far pascal 
FS_MKDIR(pcdfsi, pcdfsd, pName, iCurDirEnd, pEABuf , flags) 
struct cdfsi far * pcdfsi; 
struct cdfsd far * pcdfsd; 
char far * pName; 
unsigned short iCurDirEnd; 
char far * pEABuf; 
unsigned short flags; 
{ 
if (Is Shutdown Test) Log SD_Stats(&(pSDdata->Other_stats)); 
retum NO_ERROR; 
} 


/* FS_MOUNT flags */ 


# define 
#define 
#define 
#define 


*« 


t 


MOUNT _NEW 0 

MOUNT REMOVED 1 
MOUNT DISMOUNT 2 
MOUNT FORMAT 3 


/*** FS MOUNT - handle volume mounting 


* ENTRY flag - operation type 


t+ 4 * # 


* EXIT 


pvpftsi - VPB info (file system independent) 


pvpfsd - VPB info (file system dependent) 


hVPB - handle to VPB 
pBoot - boot sector contents 
-none- 


* RETURN NO _ ERROR if match; !NO_ERROR if fails to match 


* 


* 
* 
* 
* 
* 


This routine will accept the volume if: 


1. The Boot Sig field is 41d or greater 
2. The Boot_System_ID matches FS_NAME for all FS_NAME_LEN chars 


WARNING: 
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EFFECTS: 
uses FS_NAME{[] for ID matching 


+ + & 


*/ 


int far pascal FS_MOUNT(fiag, pvpfsi, pypfsd, hVPB, pBoot) 
unsigned short __ flag; 

struct vpfsi far * pvpfsi; 

struct vpfsd far * pvpfsd; 

unsigned short hVPB; 

char far * pBoot; 


{ 
struct Extended Boot far *ExtBoot = (struct Extended_Boot far *)pBoot; 
int i,err = NO_ERROR; 


switch (flag) { 
case MOUNT_NEW: 
/* New volume mounted, check for acceptance */ 


/* Check signature */ 


if (ExtBoot->Boot Sig < 41) 
err = INO_ERROR; 


/* Check FSD name */ 


i=0; 
do { 
if (ExtBoot->Boot System ID{i] != FS_NAME[i]) { 
err = NO_ERROR; 
break; 


} 
} while (FS_NAME[+ +i] != "\0’); 
/* Copy boot record information (if volume is accepted) */ 


if (err = = NO_ERROR) { 

pypfsi->vpi_ vid = ExtBoot->Boot_Serial; 

pypfsi->vpi_bsize = ExtBoot->Boot_BPB.BytesPerSector; 

pvpfsi->vpi_totsec = Ext8oot->Boot_BPB.TotalSectors ? 
(long)ExtBoot->Boot_BPB.TotalSectors : 
ExtBoot->Boot BPB.Ext_TotalSectors; 

pypfsi->vpi_trksec = ExtBoot->Boot_BPB.SectorsPerTrack; 

pypfsi->vpi_nhead = ExtBoot->Boot BPB.Heads; 

for (i=0; i< VOLLABELLEN; i+ +) 

pvpfsi->vpi_text{i] = ExtBoot->Boot_Vol_Labeli(i]; 
pvpfsi->vpi_text(VOLLABELLEN] = *\0’; 


break; 


case MOUNT REMOVED: 
/* Volume was removed, but references to it still exits */ 
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/* No action needed in this FSD */ 
break; : 


case MOUNT_DISMOUNT: 
/* Volume was removed and all references have been closed */ 


/* No action needed in this FSD */ 
break; 


case MOUNT_FORMAT: 
/* Accept volume blindly, format to fit this file system */ 


/* Format not allowed in this FSD */ 
err = {NO_ERROR; 


break; 
} 
if (Is Shutdown_Test) Log SD_Stats(&(pSDdata->Other_stats)); 
return(err); 
} 
int far pascal 


FS_MOVE(pcdfsi, pcdfsd, pSrc, iSrcCurDirEnd, pDst, iDstCurDirEnd, flags) 


struct cdfsi far * pcdfsi; 
struct cdfsd far * pcdisd; 
char far * pSre; 
unsigned short iSrcCurDirEnd; 
char far * pDst; 
unsigned short iDstCurDirEnd; 
unsigned short flags; 
{ 
if (is_Shutdown_Test) Log SD_Stats(&(pSDdata->Other_stats)); 
return ERROR_NOT_ SUPPORTED; 
} 
int far pascal 
FS_NEWSIZE(psffsi, psffsd, len, |Oflag) 
struct sffsi far * osffsi; 
struct sffsd far * psffsd; 
unsigned long len; 
unsigned short lOflag; 
{ 
int rc, index; 
if (lsEnabled(ENT NEWSIZE, (int far *)&index) ) { 
rc = Disable(ENT_ NEWSIZE, index); 
if (rc) return rc; 
psffsi->sfi_size = len; 
return SaveFlags(IOflag); 
} 
if (Is_ Shutdown Test) Log SD_Stats(&(pSDdata-> Other _stats)); 
return ERROR NOT SUPPORTED; 
i 


int far pascal 
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FS _NMPIPE(psftsi, psfisd, OpType, pOpRec, pData, pName) 
struct sffsi far * psffsi; ; 
struct sffsd far * psffsd; 

unsigned short OpType; 

union npoper far * pOpRec; 

char far * pData; 

char far * pName; 


{ 


int rc, index; 
unsigned short sel, off, Valid, LSeg=0, LRec = 0, LDat=0, LNam=0; 


if (isEnabled(ENT_NMPIPE, (int far *)&index) ) { 
rc = Disable(ENT_NMPIPE, index); 
if (rc) return rc; 


switch (OpType) { 

case NMP_GetPHandState: 

case NMP_SetPHandState: 
LRec = sizeof(struct phs_param); 
LDat = ((struct phs_param far *)pOpRec)->phs_dlen; 
break; 

case NMP_PipeQinto: 
LRec = sizeof(struct npi_param); 
LDat = ((struct npi_param far *)pOpRec)->npi_dien; 
break; 

case NMP_PeekPipe: 
LRec = sizeof(struct npp_param); 
LDat = ((struct npp_param far *)pOpRec)->npp_dlen; 
break; 

case NMP_ConnectPipe: 
LRec = sizeof(struct npc_param); 
LDat = ((struct npc_param far *)pOpRec)->npc_dien; 
break: 

case NMP_DisconnectPipe: 
LRec = sizeof(struct npd_param); 
LDat = ((struct npd_param far *)pOpRec)->npd_dien; 
break; 

case NMP_TransactPipe: 
LRec = sizeof(struct npt_param); 
LDat = ((struct npt_param far *)pOpRec)->npt_ilen; 
break: 

case NMP_READRAW: 
LRec = sizeof(struct npr_param); 
LDat = ((struct npr_param far *)pOpRec)->npr_dien; 
break; 

case NMP_WRITERAW: 
LRec = sizeof(struct npw_param); 
LDat = ((struct npw_param far *)pOpRec)->npw_dien; 
break; 

case NMP_WAITPIPE: 
LRec = sizeof(struct noq_param); 
LDat = ((struct npq_param far *)pOpRec)->npq_dien; 
if (pName != LNULL) { 

/* get the length of the pipe name * / 
_ while(*(pName+ (LNam+ +)) != '\0’); 
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break; 
case NMP_CALLPIPE: 
LRec = sizeof(struct npx_param); 
LDat = ((struct npx_param far *)pOpRec)->npx_ilen; 
if (pName != LNULL) { : 
/* get the length of the pipe name */ 
while(*(pName + (LNam-+ +)) != '\0’); 


break; 
case NMP_QNmPipeSemState: 
LRec = sizeof(struct qnps_param); 
LDat = ((struct qnps_param far *)pOpRec)->qnps_dien; 
break; 


default: 
return FSNMP_UNKNOWN_OPTYPE; 


} 


LSeg = (sizeof(short) * 7) + sizeof(struct sffsi) 
+ sizeof(struct sffsd) 
+ sizeof(union npoper) + LDat + LNam; 


rc = InitTCBinstanceData((unsigned short far *)&sel, 
(unsigned short far *)&off, 
{int far *)&index,LSeg); 

if (rc | | (index = = -1)) goto abort; 


/* copy sftsi struct if valid */ 

Valid = (psffsi = = LNULL) ? INVAUD : VAUD; 

rc = CopyParam(sei,(unsigned short far *)&off, 
sizeof(short), (char far *)&Vatid); 

if (rc) goto abort; 


if (Valid) { 
rc = CopyParam(sel,(unsigned short far *)&off, 
sizeof(struct sffsi),(char far *)psffsi); 
if (rc) goto abort: 


else { /* always advance the pointer */ 
off + = sizeof(struct sffsi): 
} 


/* copy sffsd struct if valid */ 

Valid = (psffsd = = LNULL) ? INVALID : VALID: 

rc = CopyParam(se!,(unsigned short far *)&off, 
sizeof(short), (char far *)&Valid); 

if (rc) goto abort; 


if (Valid) { 
rc = CopyParam(sel, (unsigned short far *)&off, 
sizeof(struct sffsd),(char far *)psffsd); 


if (rc) goto abort: 


else { /* always advance the pointer */ 
off + = sizeof(struct sffsd); 
} 


10 


15 


20 


25 


30 


35 


40 


45 


50 


55 


} 


EP 0 415 346 A2 


/* copy OpType */ 

fc = CopyParam(sel, (unsigned short far *) &off, 
sizeof(short),(char far *)&OpType); 

if (rc) goto abort; 


/* copy the data record which varies for each OpType */ 


Valid = (pOpRec = = LNULL) ? INVALID : VALID; 

rc = CopyParam(sel, (unsigned short far *)&off, 
sizeof(short), (char far *)&Valid); 

if (rc) goto abort; 


if (Valid) { 
rc = CopyParam(sel, (unsigned short far *)&off, 
LRec, (char far *)pOpRec); 
off + = sizeof(union npoper) - LRec; 
if (rc) goto abort; 


else { /* always advance the pointer */ 
off + = sizeof(union npoper); 
} 


/* copy data buffer if valid */ 

Valid = (pData = = LNULL) ? INVALID : VALID; 

rc = CopyParam(sel,(unsigned short far *)&off, 
sizeof(short),(char far *)&Valid); 

if (rc) goto abort; 


if (Valid) { 
rc = CopyParam(sel,(unsigned short far *)&off, 
LDat, (char far *)pData); 
if (rc)-goto abort; 


else { /* always advance the pointer * / 
off + = LDat: 
} 


/* copy named pipe name */ 

Valid = (pName == LNULL) ? INVALID : VALID: 

rc = CopyParam(sel, (unsigned short far *)&off, 
sizeof(short),(char far *)&Valid); 

if (rc) goto abort; 


if (Valid) { 
rc = CopyParam(sel,(unsigned short far *) &off, 
LNam, (char far *)pName); 
if (rc) goto abort; 


/* no errors occurred */ 
return NO_ERROR; 


/* this entry point not enabled to save data */ 
if (Iis_Shutdown_Test) Log SD_Stats(&(pSDdata-> Other _stats)); 
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return ERROR_NOT_SUPPORTED; 


. , abort: 

DeleteTabEntryQ; 
return Fc; 

} 

int far pascal 

FS_FINONOTIFYCLOSE (handle) 

unsigned short handle; 

{ 
if (ls_Shutdown Test) Log SO_Stats(&(pSDdata->Other_stats)); 
return ERROR_NOT_ SUPPORTED; 

} 

int far pascal 


FS_FINDNOTIFYFIRST(pcdfsi, pcdfsd, pName, iCurDirEnd, attr, handle, pData, 
cbData, pcMatch, level, timeout) 


struct cdfsi far * pcdfsi; 
struct cdfsd far * pcdfsd; 
char far * pName; 
unsigned short iCurDirEnd; 
unsigned short attr; 
unsigned short far* handle; 
char far * pData; 
unsigned short cbData; 
unsigned short far * pcMatch; 
unsigned short level: 
unsigned long timeout; 
{ 
if (Is_Shutdown_Test) Log SD_Stats(&(pSOdata->Other_stats)); 
return ERROR_NOT_SUPPORTED; 
} 
int far pascal 
FS_FINONOTIFYNEXT (handle, pData, cbData, pcMatch, infolevel, timeout) 
unsigned short handle: 
char far * pData; 
unsigned short cbData: 
unsigned short far * pcMatch; 
unsigned short infolevel: 
unsigned long timeout; 
{ 
if (Is_ Shutdown Test) Log_SD_Stats(&(pSOdata- >Other _stats)); 
return ERROR_NOT_ SUPPORTED; 
} 
int far pascal 
FS PROCESSNAME(pNameBut) 
char far *pNameBuf; 
{ 


if (Is_Shutdown_Test) Log SO_Stats(&(pSDdata->Other_stats)): 
return NO_ERROR; 
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int far pascal 
FS_RMDIR(pcdfsi, pcdfsd, pName, iCurDirEnd) 
struct cdfsi far * pcdfsi; 
struct cdfsd far * pcdfsd; 
char far * pName; 
unsigned short iCurDirEnd; 
{ 
if (Is Shutdown_Test) Log SD_Stats(&(pSDdata->Other_stats)):; 
return NO_ERROR; 
} 
int far pascal 


FS_SETSWAP(psffsi, psffsd) 


struct sffsi far * 
struct sffsd far * 


if (Is Shutdown_Test) Log SD Stats(&(pSDdata->Other_stats)): 
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psffsi; 
psffsd; 


return ERROR_NOT SUPPORTED; 


| filled reed act andl st — an ol ser e-card ere are, once sen nee n-ne esol er 2 sae ee ere ss er reel erred reer ee pes 
—_—eTFZww ewe aw Ee EST =e om amram et aw a aE Te eT Ft oF Te oT eT oe OT Tw aE ea oT oT eS a ee eee ee ee eee ee 


—— ato a oe oe ee ee a oe eee ee ee ee ee ee ee ee oe eee 


fel 


* 


** Getvpfsd - copy vpfsd data to TCB instance data area 


* ENTRY hVPB - volume parameter block handle 


* 


EXIT -none- 


* RETURN NO_ ERROR if successful 
* 


* this routine obtains a TCB instance data buffer, then copies the 


* vpfsd data it gets from FSH_GETVOLPARM into it. 


* 


* 


*« 


WARNING: 
EFFECTS: 


int Getvpfsd(hVPB) 
unsigned short hVPB; 


{ 


int rc,index: 


unsigned short sel, off, LSeg; 


struct vpfsi far * pVPBfsi; 
struct vpfsd far * pVPBfsd; 


LSeg = sizeof(vpfsdRec): 


rc = InitT CBinstanceData((unsigned short far *)&sel, 


(unsigned short far *)&off, 


(int far *)&index,LSeg); 


if (rc) goto abort; 


rc = FSH_GETVOLPARM(hVPEB, (struct vpfsi far * far *) &pVPBfsi, 


(struct vpfsd far * far *)&pVPBfsd); 


if (rc) goto abort; 


rc = CopyParam(sel,(unsigned short far *) &off,sizeof(struct vpfsd), 


(char far *)(pVPBfsd->vpd_work)); 


if (rc) goto abort; 
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return NO_ERROR; 

abort: 
DeleteTabEntry(; 
return rc; 


/*** SaveFlags - save the !Oflag parameter into this thread's data buffer 
* 
* ENTRY flags -!Oflag parameter from various FS_ entries 
* EXIT -none- | 
* RETURN NO _ ERROR if successful 
* 
* this routine obtains a TCB instance data buffer, then copies the 
* flags into it. 
* 
* WARNING: 
* EFFECTS: 
* a 
int SaveFlags(flags) 
unsigned short flags; 
{ 
int rc,index;: 
unsigned short sel, off, LSeg; 


LSeg = sizeof(BitRec); 
rc = InitTCBinstanceData((unsigned short far *)&sel, 
(unsigned short far *)&off, 
(int far *)&index,LSeg); 
if (rc) goto abort; 


rc = CopyParam(sel,(unsigned short far *)&off,sizeof(short), 
(char far *)&flags); 
if (rc) goto abort; 


return NO_ERROR; 

abort: 
DeleteTabEntry(Q); 
return rc; 


} 
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APPENDIX V 
LIBRARY 
DESCRIPTION 'BASEFSD - RSENTRYNEW testing’ 


: : NOTE: The FSD loader only supports the following rules: 
: CODE PRELOAD 

DATA PRELOAD [SINGLE | NONE] SHARED MOVABLE 
NONDISCARDABLE 


CODE PRELOAD 
DATA PRELOAD SINGLE SHARED MOVABLE 
PROTMODE 


IMPORTS 
FSHELPER. 


EXPORTS 
FS_ATTRIBUTE=_FS_ ATTRIBUTE ; OWORD attribute vector 
FS_NAME= _FS_NAME ; ASCIIZ name string | 


FS ATTACH ; From FS_ATTACH on are procedures 
FS_CHDIR 

FS _CHGFILEPTR 
FS_CLOSE 

FS_ COMMIT 
FS_COPY 

FS DELETE 

FS_EXIT 

FS _FILEATTRIBUTE 
FS_FILEINFO 
FS_FILEIO 
FS_FINDCLOSE 

FS FINDFIRST 
FS_FINDFROMNAME 
FS FINDNEXT 
FS_FINDNOTIFYCLOSE 
FS_FINDNOTIFYFIRST 
FS FINDNOTIFYNEXT 
FS_FLUSHBUF 
FS_FSCTL 
FS_FSINFO 

FS_INIT 

FS_IOCTL 

FS_MKDIR 
FS_MOUNT 

FS MOVE 

FS NEWSIZE 
FS_NMPIPE 
FS_OPENCREATE 

FS _PATHINFO 
FS_PROCESSNAME 
FS READ 

FS_RMDIR 
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FS_SETSWAP 
FS_ SHUTDOWN 
FS WRITE 


MFS_CHGFILEPTR 
MFS_CLOSE 
MFS_INIT 
MFS_OPEN 
MFS_READ 

MFS TERM 
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APPENDIX VI 
/* BASEFSD.H es 
* Sue Adams 
* Copyright 1988, Microsoft Corp. 
* 


* MODIFICATION HISTORY: 

* 89.04.07 — integrate various .h files 
* 88.10. -- initial version 

* 

/ 

j* 

* names for the different FSD’s 

at 
#if defined (generic) 


#define FSDNAME "“GENREM" 
#define VERSION “Ver 2.0 (89.04.06)\r\n’; 


#define SIGNONMSG “Multi-Threaded REMOTE/FILIO FSD\r\n"; 


unsigned long FS_ATTRIBUTE = FSA_REMOTE|FSA_LOCK; 
#elif defined(fsnmpipe) 


#define FSDNAME “UNC1" 

#define VERSION "Ver 2.0 (89.04.05) \r\n"; 

#define SIGNONMSG "UNC remote pipe test FSD\r\n"; 
unsigned long FS_ATTRIBUTE = FSA_REMOTE|FSA_UNC; 


# elif defined(onetid) 
#define FSDNAME “REM1" 


#define VERSION “Ver 2.0 (89.04.06) \r\n" 
#define SIGNONMSG “Single Threaded REMOTE FSD\r\n" 


unsigned long FS_ATTRIBUTE = FSA_REMOTE; 


#endif 


* FSH_PROBEBUF operation codes 
i 

#define READPROBE 0 

#define WRITEPROBE 1 


* defines for FS_CLOSE 
et 
#define NOT FINAL CLOSE  0x0000 


#define FINAL CLOSE THIS PROC ox0001 
#define FINAL CLOSE ALL PROC _—ox0002 


* defines for sfi_type 


zy 
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* 


#define STYPE FILE 0x0000 
#define STYPE_DEVICE0x0001 


_#define STYPE NMPIPE 0x0002 


#define STYPE FCB  0x0004 


hs 

* 

* defines for FSH_QSYSINFO 

*/ 
#define GET_MAX_SECTOR_SIZE 1 
#define GET PID 2 
#define GET TID 3 


* 


* Definitions for OPEN action codes 


if 

#define FILE EXISTS 0x0001 
#define FILE_CREATED 0x0002 
#define FILE REPLACED 0x0003 


/* FSD will know to return ERROR_OPEN_FAILED if OpenAction is the following */ 
#define UNDEFINED_ACTION Oxtfff 


* 


* Defines for fGenNeedEA parameter in FS_OPENCREATE 


* 


#define NEED EAS 0x0001 /* fGenNeedEA */ 
#define NICE_EAS 0x0000 


is 

* 

*/ 

#undef NULL 


#define NULL 0 
#define LNULL OL 


Global Definitions 


#define INVALID 0 
#define VALID 1 


#define SEM_ TIMEOUT 5000L 
#define BOGUS_CTIME0x1i111 

#define BOGUS CDATE 0x2222 
#define BOGUS _ATIME 0x3333 

#define BOGUS _ADATE 0x4444 
#define BOGUS_MTIME0x5555 
#define BOGUS MDATE Ox6666 


#define BOGUS SIZE 0x0001 
#define BOGUS POS 0x0000 
#define BOGUS WORK_CHAR ‘Q’ 


#define DEVFSOD_MSG “abc" 
#define VPFSD MSG “here is some vpfsd data” 
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* Useful Macros 

*/ 

#define MAKEFP(s,o) ((void far *)((unsigned long)((0) | ((unsigned long) (s)) < <16))) 
#define FIELDOFFSET(type,field) ((unsigned int)&(((type *)0)->field)) 


#define ISBETWEEN(,h,x) ((l< =x)&&(x< =h)) 
= 

* kernel defines for FS_FSCTL 

op 


#define GET ERR_INFO 1 /* func value */ 
#define GET_ MIN_ “MAX_ EA 2 /* func value */ 


#define ROUTE BY NAME 3 /* iArgType value */ 
#define BAD_HANDLE -1 


i? 

* enumerate the entrypoints which will save data 

*« 

/ 

enum entrypoints { 
ENT FILEINFO, 
ENT_PATHINFO, 
ENT FSCTL, 
ENT NMPIPE, 
ENT OPENCREATE, 
ENT FSINFO, 
ENT ATTACH, 
ENT FLUSHBUF, 
ENT WRITE, 
ENT READ, 
ENT NEWSIZE, 
ENT FILEIO, 
ENT COMMIT, 
ENT CLOSE, 
ENT CHGFILEPTR, 
ENTCOUNT  /* this must be last in the list! */ 


}: 


* ein Specific Error Codes (Oxef00 - Oxfeff) (always treat as unsigned) 


— eee oe eee eee eee eee eee eee eee 
=a ee a a ae FE = SP eee See ewe eee eee eee eee ee 


* 


/* when adding a new err message, update the table of strings in fsdtools.c */ 


#define START _FSD ERROR CODES Oxef00 
#define FAILURE START FSD ERROR_CODES +0 

#define FSCTL_UNKNOWN FUNCTION START FSD ERROR CODES + 1 
#define FSCTL_NO SELECTOR START FSD ERROR CODES + 2 

#define FSCTL_NO_TAB_ENTRY START FSD ERROR CODES + 3 

#define FSCTL_BUF_ OVERFLOW START_FSD_ERROR CODES + 4 
#define FSNMP_UNKNOWN_OPTYPE START FSD ERROR CODES + 5 


#define TCB_DATA EXISTS START FSD _ERROR CODES + 6 
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* The following structure is used by fsd232.c 
x 


typedef struct { 
unsigned length; 
unsigned lOflag; 
} BitRec; 


typedef struct { 
unsigned short length; 
unsigned short owner; 
unsigned short flag; 
struct sffsi thesffsi; 
struct sffsd_ thesffsd; 
unsigned short level; 
char far* pData; 
unsigned short cbData; 
unsigned short !Oflag; 

} FilelnfoRec; 


typedef struct { 
unsigned short length; 
unsigned short owner; 
unsigned short fiag; 
struct cdfsi thecdfsi; 
struct cdfsd_ thecdfsd; 
char pName[MAXPATHLEN]}; 
unsigned short iCurDirEnd; 
unsigned short level; 
charfar* pData; 
unsigned cbData; 

} PathinfoRec; 


typedef struct { 


/* recovery buffer is cast to this type*/ 


/* only verify the pointer * / 


/* only verify the pointer */ 


unsigned short 
unsigned short 
struct sffsi 
struct sffsd 
struct cdfsi 
struct cdfsd 
char 

unsigned short 
unsigned short 
unsigned short 
char far * 
unsigned short 


length; 

owner; 

thesffsi: 

thesffsd: 

thecdfsi; 

thecdfsd:; 
pName[MAXPATHLEN]; 
iCurDirEnd; 
iArgT ype; 
func; 
pParm:; 
lenParm: 


/* only verify the pointer * / 


unsigned short far * plenParmOut; 


char far * 


pData: /* only verify the pointer */ 


unsigned short lenData:; 
unsigned short far * plenDataOut: 


}FsctlRec; 


typedef struct { 


unsigned short length: 
unsigned short owner; 
unsigned short type; 

unsigned short !Oflag; 
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}CommitnCioseRec; 
/* FS_SHUTDOWN test */ 


#define BEFORE SD 1 

#define DURING SD 2 

#define AFTER SD 3 

/* type param values to FS_SHUTDOWN */ 
#define SHUTDOWN_START 0 

#define SHUTDOWN_END 1 


struct SD_Gen stats{ /* these are first in the GDT block */ 
unsigned short SD_tid; 
unsigned short FS_: “SD bad _type; 
unsigned long FS __ SD | bad_ reserved; 
unsigned long Signal ‘SD_ RAM sem; 


}; 

struct SD_FS stats { 
unsigned SD_tid_cnt; 
unsigned Other _tid_cnt; 
unsigned Attempt_cnt; 
unsigned Before_cnt; 
unsigned During_cnt; 
unsigned After_cnt; 

}; 


struct SD_stats { 
struct SD_Gen_stats General_stats; 
struct SD | FS | stats Shutdown | Stats; 
struct SD_ FS: stats Flushbuf stats: 
struct SD_ FS | stats Commit_ ‘stats: 
struct SD | FS. _ Stats Open. stats: 
struct SD_ FS Stats Read_stats; 
struct SD_ FS | _ Stats Write | stats; 
struct SD FS stats Delete stats; 
struct SD_FS_stats Other_stats; 


We claim: 
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#define TCB_ TABLE FULL START_FSD_ERROR_CODES + 7 
#define FS _ ENTRY_ ENABLED START_FSD _ERROR_ _CODES +8 

#define FS_ ENTRY_ TAB FULL START _ FSD_ ERROR CODES +9 

#define FSD | BUFFER _ OVERFLOW ~ START_ FSD_ “ERROR _CODES + 0xa 
#define FSD _ | FEALIST_ “TOO. LONG START FSD ERROR CODES + Oxb 
#define FEA _ SEGMENT _ EXISTS START_FSD_ERROR_CODES + Oxc 
#define NULL_ FEA _ SELECT OR START_FSD_ ERROR _ CODES + Oxd 

/* this value must ALWAYS be defined as the last error code above */ 

#define END_FSD ERROR_CODES NULL FEA SELECTOR 


* 


* FSD Specific Function Codes for FS_FSCTL (0x8000 - ?) (cast as unsigned) 
* Function codes 0x0000-0x7fff are reserved 


=—_ 
—_ a a oe ee oe 


/* when adding a new function, update the table of strings in fsdtoois.c */ 


#define START FSD FUNC CODES 0x8000 

#define FUNC_CLEAR_TABLE START FSD FUNC CODES + 0 

#define FUNC_ GET | BUF ~ START_ FSD_ FUNC_CODES + 1 
#define FUNC_DEL BUF START_ FSD | | FUNC CODES + 2 
#define FUNC_SEL_ TAB DUMP START_ FSD_ FUNC | - CODES + 3 
#define FUNC _TCB BUF COUNT START | FSD_ FUNC | CODES + 4 
#define FUNC_ENABLE START FSD FUNC CODES +5 

#define FUNC_ INIT _FEA_SEG START FSD FUNC CODES + 6 

#define FUNC_ DEL _ FEALIST START FSD FUNC CODES + 7 

#define FUNC | SET | SHUTDOWN_DATA ~ START_ FSD_ FUNC CODES + 8 
#define FUNC. SIGNAL_ SHUTDOWN START_ FSD FUNC | CODES +9 
#define FUNC | DISABLE START_ FSD_ FUNC | CODES + Oxa 
#define FUNC | SET EATYPE START_ FSD_ FUNC CODES + Oxb 
#define FUNC_SET OPENACTION START FSD FUNC CODES + Oxc 
/* this value must ALWAYS be equal to the last defined function above */ 

#define END FSD FUNC CODES FUNC SET _OPENACTION 


* 


* The following 2 structures are used by fsd231.c 
* data buffer is cast as these types 
* xxvalid verifies that a certain parameter is not null 
*“FS ATTACH: verifies 3rd parameter 
* FS OPENCREATE: verifies 1st parameter 
typedef struct { | /* attaching a device or drive */ 
unsigned © Si * length: 
unsigned xxvalid; 
char ddevisd[sizeof(long)];/* used by opencreate */ 
} GenericRec; 


typedef struct { /* checking hVPB */ 
unsigned _ length; 
struct vpfsd dvpfsd; 
} vpfsdRec; 


a 


— = eer eet ee oe oe oe ee ee eee eee eee eee eee eee eee ees es eee ee 
—=aSE a ee ae ee ee et oe eee ee ee eee ee ee ee eee eee eee ee ee 
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